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.

The source-recorded signed 1.1.12 baseline does not establish the newer public live HTTP contract. A release-enabled build can expose guarded Hyperliquid and KuCoin live trading; those paths must be discovered from the installed capabilities and tool schema. The reviewed 1.1.14 development source also contains a hardened HPX-RION-V2 signing and idempotency contract that must not be assumed to exist in an older installed build.

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. Signed 1.1.12-era terminal code also wrote it into %LOCALAPPDATA%\HyperionX\CodeLab\Terminal\hpx-codelab-profile.ps1; the reviewed post-1.1.12 development code reads the environment at request time and no longer serializes 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 hardened development contract 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	The source-recorded signed 1.1.12 baseline establishes Hyperion Sim place/cancel/modify/close/flatten actions but does not establish the newer public live HTTP contract. 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	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 a release-enabled route, live_trade entitlement, the provider's separate default-off setting, matching active account/instrument, connected provider, and required exchange permissions. This newer live route is not established by the source-recorded signed 1.1.12 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.

Workspace And Export Mutations

In the hardened development contract:

• 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 development contract, 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

The source-recorded signed 1.1.12 baseline does not establish the newer live route. In a 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.

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

Signed 1.1.12-era terminal code can place the bearer token in that profile, where it can outlive the process that created it. The reviewed post-1.1.12 development code no longer writes the token there; its helper reads HYPERIONX_RION_LOCAL_TOKEN from the Code Lab process environment at request time. 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.
• No established local live-order contract in the source-recorded signed 1.1.12 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.
• 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.