HyperionX API Spec

This page defines the target public contracts for HyperionX APIs. It belongs in API Reference because it is a technical contract for developers and agent integrations.

It is not a customer learning path and not the product roadmap. For learning, use Code Lab Learning Path. For product direction, use Product Roadmap.

This spec is not a promise that every endpoint or module exists in every build.

Status labels:

Status	Meaning
Current	Implemented in current desktop/runtime code.
In Progress	Public direction exists and some implementation exists, but the contract is not complete enough to treat as final.
Roadmap	Intended direction that should not be treated as available in the current build.
Internal	Exists for platform implementation but should not be treated as public API.

API Layers

Layer	Status	Consumers	Purpose
Code Lab Runtime API	Current	Script authors, AI coding agents	Indicators, strategies, bar types, optimizers, drawing, and orders.
Chart Runtime API	Current/Internal	Charts, indicators, overlays	Candle layout, panes, visible range, coordinate conversion, rendering.
Provider API	Current/Internal	Connectors	Normalize exchange, broker, simulation, and playback data.
Research API	Current/In Progress	Validator, optimizer, Rion, future CLI	Backtest, optimizer, validator, performance, saved result workflows.
Local Desktop API	Current/In Progress	Rion, local agents, future CLI	Safe localhost access to chart, Code Lab, research, drawings, news, and guarded action tools. Token checks and audit logging exist; streaming and multi-chart targeting remain roadmap items.
Permissioned Action API	Current, sim-only	Rion, local agents	Hyperion Sim order actions exist behind settings, token checks, confirmation, and audit logging. Live actions remain locked.

Code Lab Runtime Spec

Custom scripts live under:

%USERPROFILE%\Documents\HyperionX\Bin\Custom

Public script folders:

Folder	Namespace	Base type	Status
Indicators	HyperionX.Custom.Indicators	Indicator	Current
Strategies	HyperionX.Custom.Strategies	Strategy	Current
BarsTypes	HyperionX.Custom.BarsTypes	Bar type base	In Progress
ChartStyles	HyperionX.Custom.ChartStyles	Chart style base	In Progress
Optimizers	HyperionX.Custom.Optimizers	Optimizer	Current/In Progress
OptimizationFitnesses	HyperionX.Custom.OptimizationFitnesses	OptimizationFitness	Current/In Progress
Commissions	HyperionX.Custom.Commissions	Commission	Current/In Progress
MoneyManagements	HyperionX.Custom.MoneyManagements	Money management base	Current/In Progress
AddOns	HyperionX.Custom.AddOns	Addon base	Roadmap

Script Lifecycle

Required public pattern:

public override void OnStateChanged()
{
    if (State == State.SetDefaults)
    {
        Name = "My Script";
        Version = "1.0";
    }
    else if (State == State.Configured)
    {
        // Allocate series, plots, panes, child indicators, and secondary data series.
    }
}

public override void OnBarUpdate()
{
    if (CurrentBar < 1)
        return;
}

Lifecycle methods:

Method	Status	Purpose
OnStateChanged()	Current	Defaults and runtime allocation.
OnBarUpdate()	Current	Historical, playback, and real-time bar calculation.
OnTickUpdate(ICandle candle, ICandle tick)	Current	Tick-aware real-time logic.
OnAfterBarUpdate()	Current	Post-calculation hooks where supported.
OnOrderUpdate(Order order)	Current	Track order state transitions.
OnExecutionUpdate(Order order)	Current	React to fills/executions.
OnConnectionStatusChanged(...)	Current	React to provider state changes.

Script Parameters

Editable parameters:

[HyperionXProperty]
[Display(Name = "ATR Period", GroupName = "Parameters", Order = 1)]
public int AtrPeriod { get; set; }

Rules:

• Defaults are set in State.SetDefaults.
• Parameter names should be stable.
• Display groups should be consistent.
• Range validation should be used where available.
• Credentials and secrets must not be script parameters.

Series And Data

Primary series:

Open
High
Low
Close
Volume
DateTime
Input
CurrentBar
TickSize
Multiplier
Instrument

Multi-series collections:

Opens
Highs
Lows
Closes
Volumes
DateTimes
CurrentBars

Required guards:

if (CurrentBar < Period)
    return;

if (CurrentBars.Count > 1 && CurrentBars[1] < HigherPeriod)
    return;

Indicators And Plots

Indicator output should use Series<double> and Plot.

Public plot features:

• Main pane plot.
• Extra pane plot.
• Linear plot.
• Bar/histogram plot.
• Dynamic plot colors.
• Transparent plots for hidden signal channels.
• Candle body, outline, wick, and background coloring.

Drawing And Rendering

Drawing helpers:

Draw.Line
Draw.LineHorizontal
Draw.LineVertical
Draw.Arrow
Draw.Text
Draw.FixedText
Draw.HudText
Draw.Exists
Draw.Remove
Draw.Reset

Rendering spec:

• Expose visible bar range.
• Expose chart pane dimensions.
• Expose coordinate conversion: bar index to X, price to Y, Y to price.
• Expose candle width, gap, tick size, and price range.
• Require visible-range loops to clamp indices.
• Require fallback dimensions during chart load.

Rendering consumers:

• Volume profile.
• Bookmap-style overlays.
• Session tools.
• Order-flow visuals.
• Bar timers.
• Custom drawing tools.

Strategy And Order Spec

Canonical strategy order signature:

SubmitOrder(
    int selectedBarsInProgress,
    OrderAction orderAction,
    OrderType orderType,
    double quantity,
    double limitPrice,
    double stopPrice,
    string oco,
    string signalName,
    string comment = null,
    bool allowMoneyManagement = false)

Supported order actions:

Buy
Sell
SellShort
BuyToCover

Supported order types:

Market
Limit
StopMarket
StopLimit

Order lifecycle states should include:

Submitted
Accepted
Working
PartFilled
Filled
Cancelled
Rejected
Expired
Unknown

Strategy rules:

• Record entry state on fill, not on submission.
• Track working order references.
• Cancel stale working orders explicitly.
• Use OCO IDs for linked stop/target orders where supported.
• Reset trade state after full exit.
• Split reverse logic into exit order and new entry order unless a deliberate provider feature supports otherwise.

Research API Spec

Research APIs should power desktop UI, Rion, and future CLI tools.

Backtest Job

Required request fields:

{
  "strategyType": "TubeTrend",
  "instrument": "BTC-USDC",
  "connection": "My Kucoin",
  "dataSeries": {"type": "Minute", "value": 15},
  "start": "2025-05-20T00:00:00Z",
  "end": "2026-05-20T00:00:00Z",
  "parameters": {},
  "commission": "No commission",
  "slippage": 0
}

Required result sections:

• Summary metrics.
• Equity curve.
• Trades.
• Orders.
• Executions.
• Errors and warnings.

Optimizer Job

Required concepts:

• Period set.
• In-sample period.
• Out-of-sample period.
• Optional simulation period after out-of-sample.
• Parameter ranges.
• Optimizer type.
• Optimization fitness.
• Result filters.
• Best strategies count.

Minimum result tables:

• Best strategies.
• Info.
• Matrix.
• IS analysis.
• OS analysis.
• Total analysis.
• Saved result metadata.

Validator Job

Validator must support:

• Instrument lists.
• Strategy attached to a full list.
• Strategy overrides per instrument.
• Aggregate portfolio result.
• Per-instrument result drilldown.
• Saved presets.
• Saved results.

Local Desktop API Spec

The local API must bind to localhost only.

Recommended base:

http://127.0.0.1:{port}

Current endpoints:

GET /health
GET /api/v1/rion/health
GET /api/v1/rion/capabilities
GET /api/v1/rion/state
GET /api/v1/rion/chart
GET /api/v1/rion/candles?scope=analysis|recent|visible&limit=120
GET /api/v1/rion/indicators
GET /api/v1/rion/signals
GET /api/v1/rion/drawings
GET /api/v1/rion/news?scope=upcoming|today|week|all|past&limit=50&minImpact=0..3&countries=USD
GET /api/v1/rion/chart-trader
GET /api/v1/rion/orders
GET /api/v1/rion/positions
GET /api/v1/rion/scripts
GET /api/v1/rion/strategy-tools
GET /api/v1/rion/validator/status
GET /api/v1/rion/optimizer/status
GET /api/v1/rion/context
GET /api/v1/rion/memory
POST /api/v1/rion/action
POST /api/v1/rion/validator/action
POST /api/v1/rion/optimizer/action
POST /api/v1/rion/code-lab/action
POST /api/v1/rion/drawings/action
POST /api/v1/rion/trading/action

Current desktop aliases also exist under /api/v1/desktop/... for compatibility. New integrations should prefer /api/v1/rion/....

Current hardening and gaps:

• Bearer/header token checks exist for the local bridge; rotate/session-token behavior remains a hardening item.
• Explicit permission scopes are still being expanded.
• Stable chart IDs and multi-chart targeting.
• Live candle/order/position streaming.
• Terminal CLI wrapper.
• Full validator/optimizer create-test payloads.
• Live trading action scope.

Health Response

{
  "ok": true,
  "app": "HyperionX",
  "version": "1.0.0",
  "mode": "desktop",
  "timeUtc": "2026-05-20T12:00:00Z"
}

Capabilities Response

Capabilities should be explicit:

{
  "read": {
    "chartContext": true,
    "candles": true,
    "indicators": true,
    "strategies": true,
    "chartTrader": true,
    "chartDrawings": true,
    "economicNews": true
  },
  "codeLab": {
    "listScripts": true,
    "compile": true,
    "diagnostics": true
  },
  "research": {
    "backtest": true,
    "validator": true,
    "optimizer": true
  },
  "simulationTrading": {
    "enabled": false,
    "placeOrder": false,
    "cancelOrder": false,
    "modifyOrder": false,
    "flatten": false
  },
  "liveTrading": {
    "enabled": false
  }
}

Context Response

Context should include:

• Active chart.
• Visible candles.
• Recent candles.
• Loaded indicators.
• Loaded strategies.
• Chart Trader state.
• Account labels safe for display.
• Working orders where permission allows.
• Positions where permission allows.
• Data freshness.
• Provider connection status.

Secrets must not be returned.

Chart Drawings Response

GET /api/v1/rion/drawings returns drawing state for the active chart.

Response shape:

{
  "status": "OK",
  "handled": true,
  "message": "Current chart drawings.",
  "activeChart": {
    "symbol": "BTC-USDC",
    "timeFrame": "5 Minute",
    "totalCandleCount": 500,
    "visibleCandleCount": 120
  },
  "drawings": [
    {
      "id": "7d4f...",
      "name": "RION: London High 78000.0",
      "type": "HorizontalLine",
      "label": "London High 78000.0",
      "isAgentDrawing": true,
      "startBarIndex": 100,
      "endBarIndex": 220,
      "startPrice": 78000.0,
      "endPrice": 78000.0,
      "color": "#13A8FF",
      "opacity": 0.95,
      "width": 1.35,
      "dashStyle": "Dash",
      "isLocked": false,
      "isVisible": true,
      "zOrder": 12
    }
  ]
}

Chart Drawings Action Request

POST /api/v1/rion/drawings/action performs a drawing tool action on the active chart.

Current request fields:

Field	Type	Notes
action	string	Required unless command is supplied.
command	string	Optional natural command such as draw London highs and lows.
scope	string	visible, recent, or omitted.
replaceExistingAgentDrawings	boolean	Removes prior RION: drawings before drawing new ones.
clearAllDrawings	boolean	Required for clear_all_drawings.
drawLabels	boolean	Controls label text drawings.
lookbackBars	number	Support/resistance calculation lookback.
maxLevels	number	Maximum support/resistance levels.
sessionStart / sessionEnd	string	Session window for London range, such as 02:00.
levels	array	Explicit level definitions for draw_levels.

Supported actions:

• list_drawings
• clear_agent_drawings
• clear_all_drawings
• draw_levels
• draw_high_low_range
• draw_london_range
• draw_support_resistance

Example high/low request:

{
  "action": "draw_high_low_range",
  "scope": "visible",
  "replaceExistingAgentDrawings": true,
  "drawLabels": true
}

Example explicit levels request:

{
  "action": "draw_levels",
  "replaceExistingAgentDrawings": true,
  "drawLabels": true,
  "levels": [
    {
      "price": 78000.0,
      "kind": "resistance",
      "label": "Resistance 78000",
      "color": "#FF4E4E",
      "dashStyle": "Dash",
      "width": 1.5,
      "opacity": 0.95
    }
  ]
}

Drawing action response:

{
  "status": "OK",
  "handled": true,
  "tool": "chart_drawings/draw_high_low_range",
  "message": "Drew high/low from 120 candle(s): high 78120.0, low 77680.0.",
  "createdCount": 4,
  "removedCount": 0,
  "activeChart": {
    "symbol": "BTC-USDC",
    "timeFrame": "5 Minute",
    "totalCandleCount": 500,
    "visibleCandleCount": 120
  },
  "drawings": []
}

Rion-created drawings must use the RION: prefix so clear_agent_drawings can remove agent drawings without touching manual user drawings. clear_all_drawings must remain guarded by clearAllDrawings: true.

Economic News Response

GET /api/v1/rion/news exposes the economic calendar events used by the News window and NewsEcon indicator.

Query parameters:

Parameter	Type	Default	Notes
scope	string	upcoming	upcoming, today, week, all, or past.
limit	number	50	Clamped from 1 to 250.
minImpact	number	0	0 to 3; 3 is high impact.
countries	string	empty	Comma, semicolon, or space-separated country codes such as USD,EUR.
search	string	empty	Filters title, country, or impact text.
refreshHours	number	12	Calendar cache refresh window, clamped from 1 to 24.

Example:

GET /api/v1/rion/news?scope=upcoming&limit=20&minImpact=2&countries=USD

Response shape:

{
  "status": "OK",
  "message": "Loaded 3 economic news event(s).",
  "source": "EconomicNewsCalendarService",
  "scope": "upcoming",
  "localTime": "2026-05-21T09:30:00",
  "totalLoadedCount": 48,
  "eventCount": 3,
  "events": [
    {
      "id": 12345,
      "timeLocal": "2026-05-21T10:00:00",
      "minutesFromNow": 30.0,
      "country": "USD",
      "impact": "High",
      "impactValue": 3,
      "title": "Existing Home Sales",
      "previous": "4.02M",
      "forecast": "4.10M"
    }
  ]
}

Action Request

All action requests should use a single envelope:

{
  "id": "client-generated-id",
  "action": "place_sim_order",
  "mode": "simulation",
  "dryRun": false,
  "parameters": {
    "chartId": "active",
    "account": "Hyperion Sim",
    "instrument": "BTC-USDC",
    "side": "buy",
    "orderType": "market",
    "quantity": 0.01
  }
}

Action responses must never imply success unless the platform confirms it:

{
  "id": "client-generated-id",
  "handled": true,
  "accepted": true,
  "confirmed": false,
  "state": "submitted",
  "message": "Order submitted but not filled yet.",
  "orderId": "local-order-id",
  "auditId": "audit-id"
}

If no order was created:

{
  "handled": true,
  "accepted": false,
  "confirmed": false,
  "state": "not_submitted",
  "message": "No order was submitted. Chart Trader is not connected or trading permission is disabled."
}

Permissioned Action Spec

Action groups:

Group	Actions	Default
Read	chart context, candles, indicators, strategies, account labels	Enabled
Code Lab	list scripts, open Code Lab, compile custom scripts, status	Permissioned/current partial
Research	validator and optimizer open/setup/run/cancel/status	Permissioned/current partial
Simulation Trading	place, cancel, modify, flatten sim orders	Off
Live Read	live orders, positions, executions, balances	Off
Live Trading	place, cancel, modify, flatten live orders	Off

Simulation trading requirements:

• User setting must enable simulation trading tools.
• Account must be simulation.
• Request must specify action and quantity.
• Response must include whether an order was actually created.
• Request must include confirmed=true or the legacy executeTrading=true flag.
• Audit logging must record request, result, permission group, account/instrument context when available, and timestamp.

Live trading requirements:

• Separate setting from simulation.
• Provider capability check.
• Account allowlist.
• Max order size.
• Max daily loss or risk control where available.
• Confirmation workflow.
• Audit log.
• Emergency disable.

API Compatibility Rules

Stable API rules:

• Version every external contract.
• Prefer JSON objects over positional arrays.
• Include schemaVersion where responses can evolve.
• Include status, message, and errors for tool calls.
• Redact secrets.
• Return explicit capability flags.
• Do not expose private WPF controls or internal object references.
• Do not require screen scraping.
• Do not let AI report actions that were not confirmed by HyperionX.

Minimum Production API Checklist

For the first complete Rion/local-agent workflow, HyperionX should expose:

• GET /health.
• GET /api/v1/rion/capabilities.
• GET /api/v1/rion/context.
• Code Lab compile diagnostics.
• Active chart candle snapshot.
• Loaded indicator list and parameters.
• Loaded strategy list and parameters.
• Active chart drawing list and Rion drawing actions.
• Economic news event snapshot.
• Chart Trader read state.
• Validator run action.
• Optimizer run action.
• Simulation-only place, cancel, modify, and flatten actions behind a setting.
• Action audit log.
• Clear failure responses when a requested action is unavailable.