Local Desktop API

The Rion Local Desktop API lets a provisioned local process inspect the active HyperionX workspace and request selected desktop actions.

Preview interface

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.

Reviewed 1.1.27 source contains guarded Hyperliquid and KuCoin live routes and the HPX-RION-V2 signing/idempotency contract described below. This is source evidence, not a guarantee that an installed public release exposes those features. Check the documentation version map, then discover the installed capabilities and tool schema before using a route.

The scoped HTTP routes are separate from Rion's conversational tools. In reviewed 1.1.27 source, default Cloud chat uses grounded chart, indicator, supported high/low drawing, and task-owned indicator-authoring tools. It does not expose trading or legacy research-execution tools. A chat request or a profile instruction does not turn those missing tools into HTTP route calls. See AI Agent.

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.

Code Lab receives the token through its child-process environment. Older terminal code also wrote it into %LOCALAPPDATA%\HyperionX\CodeLab\Terminal\hpx-codelab-profile.ps1; reviewed 1.1.27 source reads the environment at request time and does not serialize the token into that profile. Check the installed build and follow Code Lab Token Handling if an existing profile contains a token.

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.

Request Signing, Request IDs, And Idempotency

Always read the installed capabilities response before implementing signing. The contract in reviewed 1.1.27 source advertises version: HPX-RION-V2, mutationRequestIdRequired: true, its key ID, and this canonical form:

HPX-RION-V2\nKEY_ID\nREQUEST_ID\nMETHOD\nPATH\nQUERY\nTIMESTAMP\nBODY

Configuration uses:

• HYPERIONX_RION_SIGNING_SECRET for the HMAC secret.
• HYPERIONX_REQUIRE_RION_SIGNATURE to require signing.
• HYPERIONX_RION_SIGNING_KEY_ID for the expected key ID; the default is local-v1.
• HYPERIONX_ALLOW_LEGACY_RION_READ_SIGNATURES to allow or reject deprecated legacy signatures on non-mutation requests.

For HPX-RION-V2:

• Use uppercase HTTP method.
• Normalize the path to lowercase and remove a trailing slash except for /.
• Use the raw query text without the leading ?.
• Use the exact timestamp header and exact UTF-8 body text sent on the wire.
• Include the same X-HyperionX-Key-Id and X-HyperionX-Request-Id values in the canonical text and headers.
• Generate HMAC-SHA256 and send lowercase hexadecimal or Base64.

The timestamp window is five minutes. Every POST request in the hardened contract requires a valid X-HyperionX-Request-Id, even when signing is optional. The in-process idempotency cache retains completed POST results for approximately ten minutes, up to 10,000 entries:

• Reusing the same request ID with the same method, normalized path, query, key ID, and body returns the stored response with X-HyperionX-Idempotent-Replay: true.
• Reusing it for a different mutation returns HTTP 409.
• The cache is not durable across application restart and does not promise protection after its retention window.

Use this expired vector only for offline verification:

secret: hpx-docs-test-secret
key id: local-v1
request id: docs-test-0001
method: POST
path: /api/v1/rion/trading/action
query: <empty>
timestamp: 2026-08-01T12:00:00Z
body: {"action":"cancel","dryRun":true}

canonical:
HPX-RION-V2
local-v1
docs-test-0001
POST
/api/v1/rion/trading/action

2026-08-01T12:00:00Z
{"action":"cancel","dryRun":true}

expected hex:
5e6bb71f5c752a4f6cb5aad6d1d4834db6e5e789b6e89482d31237971a0698b6

expected base64:
Xmu3H1x1Kk9starW0dSDTbbl54m26JSC0xI3lxoGmLY=

Compatibility and unknown outcomes

Older builds can advertise the legacy five-line signature instead and may not require or deduplicate request IDs. Never send an HPX-RION-V2 request unless the installed capabilities advertise it. For any timed-out or unknown mutation, reuse the original request ID only within the advertised idempotency contract; otherwise reconcile orders and positions before deciding whether another request is safe.

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.
Signal excursion study	GET /api/v1/rion/signals/excursions?includeSignals=false	Computes the active Rion signal studies without writing files in the hardened contract.
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.
Chart history	POST /api/v1/rion/chart/action	Uses chart permission in the hardened contract, caps the requested period at 365 days, and can change the active chart instrument, timeframe, and history range. Set dryRun: true to preview the resolved request.
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.
Signal excursion export	POST /api/v1/rion/signals/excursions/export	Uses optimize permission in the hardened contract and writes requested CSV/JSON studies beneath Documents\HyperionX\RionStudies.
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	Hyperion Sim place/cancel/modify/close/flatten actions, plus guarded Hyperliquid and KuCoin routes in reviewed 1.1.27 source. Use only the paths exposed by the installed build after provider-specific capability, setting, entitlement, active account/instrument, connection, and exchange-permission checks pass.

Supported action names for the scoped Code Lab route are open, list, compile, and status. That route does not provide validate-script or source-file editing. The reviewed 1.1.27 grounded conversation's task-owned indicator authoring is a different tool surface; see Code Lab Automation Boundary. A conversational compile still does not prove runtime correctness.

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	Read routes, chat entry, and command classification	Valid desktop token. In the hardened contract, GET signal-excursion analysis is in-memory and does not export files.
chart	Active-chart history changes	desktop_tools entitlement. The hardened contract limits a request to 365 days.
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 an enabled installed route, live_trade entitlement, the provider's separate default-off setting, matching active account/instrument, connected provider, and required exchange permissions. Reviewed source alone does not establish installed availability.

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.

Workspace And Export Mutations

In the hardened contract present in reviewed 1.1.27 source:

• POST /api/v1/rion/chart/action requires chart, accepts dryRun, and rejects periods greater than 365 days.
• GET /api/v1/rion/signals/excursions is read-only.
• POST /api/v1/rion/signals/excursions/export requires optimize, writes the study files, and is included in the mutation audit/idempotency path.

Older Preview builds can expose a different permission or export boundary. If the installed tool schema labels chart mutation as read or makes the GET study export files, do not assume the hardened contract; upgrade or isolate that integration and treat the token as workspace/file-write capable.

Trading Dry Runs

In the hardened contract present in reviewed 1.1.27 source, POST /api/v1/rion/trading/action validates the selected account/provider policy, structured size/price/leverage/size-mode/route fields, and whether the current Chart Trader can produce a confirmation for the requested action before returning wouldExecute: true. The dry run does not apply the requested inputs to Chart Trader and does not transmit an order.

The returned confirmation can still be based on the Chart Trader's currently configured size or leverage while the separate requestedInputs object reports the values supplied by the caller. Compare both. Until the confirmation is built from the complete non-mutating candidate order, treat it as an action-feasibility check rather than a complete requested-order preview.

Dry-run success is still not an exchange acceptance or fill guarantee. Funds, collateral, price movement, provider increments, provider risk checks, network state, and exchange state can change before execution. Do not promote a result automatically without displaying and confirming the returned request and current account state.

Older installed builds can implement a narrower access-only dry run. Treat a response that does not include the expected confirmation and requested-input details as a limited compatibility result and validate every field independently.

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.

In the hardened contract, an unconfirmed non-dry-run request returns CONFIRMATION_REQUIRED before applying supplied size, price, or leverage to Chart Trader. An older build can stage those values earlier, so use dryRun for previews and inspect the active Chart Trader after any compatibility-mode request.

A responsible client must:

1. show the intended account, symbol, side, type, price, and quantity to the user
2. wait for explicit approval unless the user deliberately enabled a supported auto-execute policy
3. set the confirmation field only after that decision
4. check the returned status before claiming that anything occurred

Follow Local Agent Live Trading API only in an enabled installed build, and fail closed unless the provider-specific capability and tradingAccess.allowed explicitly enable the selected account and instrument. The documentation version map separates source review from release evidence.

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.

Code Lab Token Handling

HyperionX launches Code Lab with the selected API address and bearer token in the child-process environment. The current embedded terminal creates this PowerShell profile:

%LOCALAPPDATA%\HyperionX\CodeLab\Terminal\hpx-codelab-profile.ps1

Older terminal code can leave the bearer token in that profile, where it can outlive the process that created it. Reviewed 1.1.27 source does not write the token there; its helper reads HYPERIONX_RION_LOCAL_TOKEN from the Code Lab process environment at request time. Upgrading does not by itself prove an old file is clean. Neither mechanism is a supported bootstrap contract for an unrelated integration.

After using Code Lab on a shared, lost, or potentially compromised Windows account:

1. Close HyperionX, Code Lab, and their terminal processes.
2. Remove the terminal profile if it is no longer needed.
3. Restart HyperionX so an app-generated process token changes.
4. If HYPERIONX_RION_LOCAL_TOKEN supplied a stable token, rotate that configured value before restarting; deleting the file alone does not revoke it.

The profile can be recreated the next time Code Lab starts. Inspect it after an upgrade and restrict Windows-account and file access accordingly. If the installed build still serializes the token, repeat cleanup or avoid opening the embedded terminal until a hardened build is installed.

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 hx CLI.
• Reviewed source availability does not establish a public live-order contract; Hyperliquid and KuCoin support remains 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.
• Hardened POST idempotency is in-memory and time-bounded; it is not durable across restart or guaranteed after cache expiry.
• Legacy builds can lack V2 signing/idempotency and can expose broader read behavior. Use the installed capability and schema payloads rather than assuming this page's newest contract.

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.