Connect A Local Agent To HyperionX Live Trading

The HyperionX Local Desktop API lets a third-party Python, JavaScript, or AI agent on the same Windows computer read platform state and request orders through a selected Hyperion Sim, live Hyperliquid, or live KuCoin account.

Preview and version boundary

The source-recorded signed 1.1.12 baseline does not establish the newer live HTTP contract. Reviewed 1.1.14 development source adds live Hyperliquid and live KuCoin routing plus a hardened request-signing/idempotency contract. Use a live path only when the installed build exposes the matching setting and capability; do not infer availability from a source version alone.

An entitlement or HTTP route by itself does not enable live trading. Fail closed unless the installed capabilities and selected trading state explicitly allow the intended account and instrument.

The agent does not need HyperionX source code and does not receive exchange private keys. It calls the loopback HTTP API; HyperionX validates the selected account, instrument, license, settings, connection, and exchange permissions before routing an order through its normal order pipeline.

Local agent
    ↓
127.0.0.1 HyperionX Local Desktop API
    ↓
HyperionX entitlement, setting, account, and provider guards
    ↓
Selected Hyperion Sim, Hyperliquid, or KuCoin account

Read Local Desktop API for the shared authentication, signing, audit, and compatibility boundaries. Hyperliquid users must also read Hyperliquid Wallet.

Supported Trading Accounts

Account	Permission	Separate setting	Additional boundary
Hyperion Sim (LocalPaper)	sim_trade	Hyperion Sim order actions	Simulation only. The Sim auto-execute setting applies only to this account type.
Live Hyperliquid	live_trade	Live Hyperliquid local-agent actions	Requires a matching Hyperliquid instrument, connected wallet, broker support, and builder-fee approval when configured.
Live KuCoin Spot or Futures	live_trade	Live KuCoin local-agent actions	Requires a matching KuCoin provider scope and validated API trading capability for the selected Spot or Futures market.

Server-paper accounts and every other Broker connection are blocked by the local-agent trading policy.

All three settings are off by default. Enabling Hyperion Sim does not enable either live provider. Enabling Hyperliquid does not enable KuCoin, and enabling KuCoin does not enable Hyperliquid.

Requirements

Before connecting an agent, confirm that:

• HyperionX is running.
• The agent runs under the same trusted Windows user on the same computer.
• The installed build reports the intended trading capability.
• The license has the required sim_trade or live_trade entitlement.
• The intended account is connected and funded in HyperionX.
• A chart for the intended instrument is active.
• The matching account is selected in Chart Trader.
• The matching trading setting is enabled in Rion Ai Settings.
• The agent has the local bearer token.

127.0.0.1 is loopback-only. A process on another computer cannot connect directly, even when it is on the same LAN. Do not forward or proxy the Local Desktop API ports.

1. Configure The Trading Account

Hyperion Sim

1. Connect the provider that supplies the intended market data.
2. Open a supported instrument chart.
3. Select LocalPaper / Hyperion Sim in Chart Trader.
4. Confirm the active chart and account before every action.

Hyperliquid

In HyperionX:

1. Create or select the Hyperliquid connection.
2. Connect the wallet and complete the required API-wallet setup.
3. Enable trading for the connection.
4. Complete builder-fee approval when configured.
5. Open a Hyperliquid instrument chart.
6. Select the live Hyperliquid account in Chart Trader.

The local agent receives the HyperionX bearer token, not the main-wallet private key, seed phrase, WalletConnect payload, wallet signature, or locally protected Hyperliquid agent key.

KuCoin

In HyperionX:

1. Create or select the KuCoin connection.
2. Choose one authentication method:
   • OAuth Login: first validate the HyperionX cloud session, then authorize the linked account on KuCoin's website.
   • Manual Classic API key: enter the dedicated API key, secret, passphrase, and matching API-key version in the connection settings, then select Test Credentials.
3. Approve only the KuCoin permissions the user intends to use. Do not grant Withdrawal permission.
4. Connect and let HyperionX validate the OAuth or manual Spot and Futures capabilities.
5. Open the intended KuCoin instrument chart.
6. Select the matching scoped account in Chart Trader:
   • KuCoin Spot for Spot instruments
   • KuCoin Futures USDT for USDT-settled Futures
   • KuCoin Futures USDC for USDC-settled Futures

HyperionX rejects mismatches such as a Futures USDC account selected for a Futures USDT instrument. The local agent never needs the KuCoin API secret or passphrase.

Do not switch an existing entry casually between OAuth and manual credentials. A manual credential test changes the active local mode without remotely unlinking OAuth, while OAuth disconnect returns the entry to manual mode without clearing previously saved manual fields. Follow Connect KuCoin to revoke or clear the unused credential set and verify the final mode.

KuCoin Skills Hub is not required. HyperionX routes through its connected KuCoin Classic provider and applies its own local-agent policy.

2. Enable The Intended Trading Mode

Open Rion Ai Settings and find Local API Access.

Enable only the required setting:

• Allow Rion to place, cancel, flatten, or modify Hyperion Sim orders
• Allow local agents to trade a selected live Hyperliquid account
• Allow local agents to trade a selected live KuCoin account

The live checkboxes display a real-funds warning the first time they are enabled.

The Hyperion Sim auto-execute checkbox applies only to Sim. A live HTTP request must explicitly set confirmed or executeTrading to true; enabling a provider setting does not authorize unattended live execution by itself.

Agent Builder profile text and numeric risk fields are not global HTTP-token scopes. Do not treat them as enforced limits unless a later installed build explicitly reports that enforcement.

3. Configure The Bearer Token

The API uses HYPERIONX_RION_LOCAL_TOKEN when that user environment variable exists. Otherwise HyperionX creates an in-memory token for the current run.

For a stable token, close HyperionX, run this PowerShell, store the displayed token securely, and restart HyperionX:

$hxTokenBytes = [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
$hxToken = [Convert]::ToBase64String($hxTokenBytes).TrimEnd('=').Replace('+', '-').Replace('/', '_')

[Environment]::SetEnvironmentVariable(
    'HYPERIONX_RION_LOCAL_TOKEN',
    $hxToken,
    'User'
)

$hxToken

Do not:

• commit the token to source control
• embed it in source code or a URL
• put it in an agent prompt
• print it in application logs
• share it with another user
• send it to a cloud model

The current public desktop does not expose a supported control for copying its generated process token into an arbitrary external integration. Do not scrape logs or process memory to obtain one.

Check older Code Lab terminal profiles

HyperionX passes the Local Desktop API token to Code Lab through the child-process environment. Signed 1.1.12-era terminal code also wrote it into %LOCALAPPDATA%\HyperionX\CodeLab\Terminal\hpx-codelab-profile.ps1. Reviewed post-1.1.12 development code reads the environment at request time and no longer serializes the token into that file.

Do not treat the profile as a supported token-discovery mechanism. After upgrading, inspect it without sharing its contents. If it contains a token, close HyperionX and Code Lab, remove the profile if it is no longer needed, restart HyperionX, and rotate any stable configured token. Deleting the file alone does not revoke HYPERIONX_RION_LOCAL_TOKEN.

The capabilities response can also describe an optional HMAC request-signing policy. Follow the policy documented in Local Desktop API when signing is required.

4. Find The Local API Address

HyperionX first listens on:

http://127.0.0.1:5217

If that port is occupied, it tries ports through 5226. A client with a provisioned token can probe the range with the authenticated health endpoint:

$hxToken = [Environment]::GetEnvironmentVariable(
    'HYPERIONX_RION_LOCAL_TOKEN',
    'User'
)
$hxHeaders = @{ Authorization = "Bearer $hxToken" }
$hxBaseUrl = $null

foreach ($hxPort in 5217..5226) {
    try {
        $hxCandidate = "http://127.0.0.1:$hxPort"
        $hxHealth = Invoke-RestMethod `
            -Uri "$hxCandidate/api/v1/rion/health" `
            -Headers $hxHeaders `
            -TimeoutSec 1

        if ($hxHealth.status -eq 'OK') {
            $hxBaseUrl = $hxCandidate
            break
        }
    }
    catch {}
}

$hxBaseUrl

Every request must include:

Authorization: Bearer YOUR_LOCAL_API_TOKEN

A missing or invalid token returns HTTP 401. An authenticated request can still be denied by its action-specific permission and trading-access checks. Inspect the HTTP status and JSON body.

5. Check Capabilities And Selected Trading Access

Query the installed build rather than assuming a provider is enabled:

GET /api/v1/rion/health
GET /api/v1/rion/capabilities
GET /api/v1/rion/tools/schema
GET /api/v1/rion/state
GET /api/v1/rion/orders

The capabilities response exposes separate permission values:

• simTrade
• liveHyperliquidTrade
• liveKucoinTrade
• aggregate liveTrade and trade values

The orders response includes the guarded active trading state:

• selected account and account type
• active symbol and connection
• isHyperionSim, isLiveHyperliquid, and isLiveKucoin
• resolved sim_trade or live_trade permission
• tradingAccess.allowed
• the classified account kind and label
• a denial message when the selected context is not allowed

An automated client must check state before every order and stop when tradingAccess.allowed is not exactly true.

Guarded Denial Conditions

HyperionX denies a local-agent trading action when any applicable check fails, including:

• the selected account or instrument is missing
• the trading account does not match the active chart connection
• the account is Server Paper or an unsupported Broker provider
• the required sim_trade or live_trade entitlement is absent
• the separate account-type setting is disabled
• the Hyperliquid instrument does not route to Hyperliquid
• the Hyperliquid wallet is disconnected
• the Hyperliquid connection does not support broker trading
• configured Hyperliquid builder-fee approval is incomplete
• the KuCoin instrument is not recognized as Spot or Futures
• the KuCoin account scope does not match the selected instrument
• the KuCoin connection is disconnected
• the KuCoin API key lacks validated broker or selected-market trading capability

Do not infer trading access from permissions.liveTrade alone. The selected account and instrument still must pass tradingAccess.

6. Dry-Run An Order

POST /api/v1/rion/trading/action
Content-Type: application/json
Authorization: Bearer YOUR_LOCAL_API_TOKEN
X-HyperionX-Request-Id: A_NEW_UNIQUE_PREVIEW_ID

{
  "action": "place",
  "side": "buy",
  "route": "limit",
  "price": 78000,
  "size": 50,
  "sizeMode": "USD",
  "leverage": 1,
  "confirmed": false,
  "executeTrading": false,
  "dryRun": true
}

HyperionX resolves the selected account to sim_trade or live_trade and runs its current trading-access policy before returning a successful dry run.

Dry run is not an exchange acceptance guarantee

In the hardened development contract, dryRun: true checks the selected account/provider policy, validates structured field syntax, and verifies that the current Chart Trader can produce a confirmation for the action. It does not send an order or apply the requested inputs to Chart Trader.

The returned confirmation can still reflect the Chart Trader's currently configured size or leverage while requestedInputs reports the values supplied by the caller. Compare both before approval. Provider increments, funds, collateral, price, network, risk, and exchange state are not guaranteed until the real request is processed.

Older installed builds can provide only the narrower access preflight. Do not automatically convert any successful dry run into a live request.

A successful result includes:

• status: "OK"
• handled: true
• dryRun: true
• wouldExecute: true
• the resolved permission
• the classified account kind and label
• in the hardened contract, confirmation plus the separate requestedInputs

It does not send an order. A dry run cannot guarantee exchange acceptance because balances, prices, permissions, and connection state can change.

7. Send The Confirmed Order

After checking capabilities, tradingAccess, the dry-run response, active account, symbol, and the user's decision, create the confirmed execution body. Assign it a new request ID because it differs from the dry-run body. Reuse that execution ID only when retrying the exact same body under an installed idempotency contract:

{
  "action": "place",
  "side": "buy",
  "route": "limit",
  "price": 78000,
  "size": 50,
  "sizeMode": "USD",
  "leverage": 1,
  "confirmed": true,
  "executeTrading": true,
  "dryRun": false
}

The example values are illustrative. The order remains subject to HyperionX validation, provider rules, available funds or collateral, instrument increments, and exchange acceptance.

The hardened contract returns CONFIRMATION_REQUIRED before applying supplied size, price, or leverage when neither confirmation field is set. Older builds can stage those values earlier, so use dryRun: true for previews and verify the visible Chart Trader after any compatibility-mode request.

The confirmed and executeTrading fields assert that the caller obtained authorization. A direct HTTP request does not open an independent desktop confirmation dialog. Live calls cannot use the Hyperion Sim auto-execute setting.

Do not treat HTTP 200, status: OK, or handled: true alone as proof of a fill.

Trading Request Fields

The installed tool schema is authoritative.

Field	Type	Description
action	string	place, cancel, flatten, close, or modify
side	string	buy or sell
route	string	market, bid, ask, limit, or stop
price	number	Price used by limit, stop, or modification actions
size	number	Order size
quantity	number	Alternative quantity field
sizeMode	string	USD or Qty
leverage	integer	Requested leverage, with a minimum of 1
selector	string	Working-order selector for a modification
confirmed	boolean	Asserts that the caller obtained execution approval
executeTrading	boolean	Requests actual execution
dryRun	boolean	Runs the installed non-transmitting preflight. Hardened builds validate structured syntax and current action feasibility; older builds can perform only account/provider access checks.
command	string	Optional natural-language command instead of structured fields

Use structured JSON fields for automated agents. Natural-language commands are less deterministic and should not be used for unattended live execution.

Supported Order Routes

Route	Behavior
market	Requests a market order
bid	Requests a limit order at the current bid
ask	Requests a limit order at the current ask
limit	Requests a limit order at the supplied price
stop	Requests a stop order at the supplied price

Cancel, Flatten, Close, And Modify

Cancel working orders in the active trading context:

{
  "action": "cancel",
  "confirmed": true,
  "executeTrading": true,
  "dryRun": false
}

Flatten the active position:

{
  "action": "flatten",
  "confirmed": true,
  "executeTrading": true,
  "dryRun": false
}

Close the active position:

{
  "action": "close",
  "confirmed": true,
  "executeTrading": true,
  "dryRun": false
}

Modify an order price:

{
  "action": "modify",
  "selector": "stop",
  "price": 77500,
  "confirmed": true,
  "executeTrading": true,
  "dryRun": false
}

Modify an order quantity:

{
  "action": "modify",
  "quantity": 0.002,
  "sizeMode": "Qty",
  "confirmed": true,
  "executeTrading": true,
  "dryRun": false
}

The exact scope of cancel, flatten, close, and selector follows the active Chart Trader context and installed tool schema. Use a dry run, then independently confirm that the requested action and target exist before enabling execution.

8. Verify The Result

GET /api/v1/rion/orders
GET /api/v1/rion/positions

Read the JSON action result, then determine whether the order is working, filled, partially filled, cancelled, or rejected. Reconcile against the authoritative Hyperliquid or KuCoin account for live actions.

If a request times out, do not immediately repeat it. The first request might have reached HyperionX or the provider. Check orders and positions before deciding whether a retry is safe.

Minimal Python Client

Install Requests in the agent's isolated environment if needed:

python -m pip install requests

This client discovers HyperionX, checks the provider-specific permission and selected trading access, then submits a dry run. Live execution remains disabled:

import os
import uuid

import requests


token = os.environ["HYPERIONX_RION_LOCAL_TOKEN"]
session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
})


def find_hyperionx():
    for port in range(5217, 5227):
        url = f"http://127.0.0.1:{port}"
        try:
            response = session.get(f"{url}/api/v1/rion/health", timeout=1)
            if response.ok and response.json().get("status") == "OK":
                return url
        except requests.RequestException:
            pass
    raise RuntimeError("HyperionX Local Desktop API was not found")


def get_json(base_url, path):
    response = session.get(f"{base_url}{path}", timeout=10)
    response.raise_for_status()
    return response.json()


base_url = find_hyperionx()
capabilities = get_json(base_url, "/api/v1/rion/capabilities")
state = get_json(base_url, "/api/v1/rion/state")
orders = get_json(base_url, "/api/v1/rion/orders")

signing = ((capabilities.get("auth") or {}).get("requestSigning") or {})
if signing.get("required") is True:
    raise RuntimeError("This minimal example does not implement the advertised request-signing contract")

access = orders.get("tradingAccess") or {}
account_kind = access.get("accountKind")
permission_field = {
    "HyperionSim": "simTrade",
    "LiveHyperliquid": "liveHyperliquidTrade",
    "LiveKucoin": "liveKucoinTrade",
}.get(account_kind)

permissions = capabilities.get("permissions") or {}
if not permission_field or permissions.get(permission_field) is not True:
    raise RuntimeError("The selected trading mode is not enabled")
if access.get("allowed") is not True:
    raise RuntimeError(access.get("message") or "Trading access was denied")

print("Current state:", state)
print("Trading access:", access)

order = {
    "action": "place",
    "side": "buy",
    "route": "limit",
    "price": 78000,
    "size": 50,
    "sizeMode": "USD",
    "leverage": 1,
    "confirmed": False,
    "executeTrading": False,
    "dryRun": True,
}

preview = session.post(
    f"{base_url}/api/v1/rion/trading/action",
    json=order,
    headers={"X-HyperionX-Request-Id": uuid.uuid4().hex},
    timeout=15,
)
preview.raise_for_status()
preview_result = preview.json()

if (
    preview_result.get("status") != "OK"
    or preview_result.get("handled") is not True
    or preview_result.get("wouldExecute") is not True
):
    raise RuntimeError(preview_result.get("message") or "Dry run was denied")

print("Dry-run result:", preview_result)

# Live execution is intentionally omitted. Add it only after implementing
# explicit user approval, fresh state checks, timeout reconciliation, and
# provider-specific operational limits.

Do not implement capability validation by searching JSON text for the word live. Parse the fields defined by the installed response and require the permission that matches tradingAccess.accountKind.

Security And Emergency Stop

• Keep the service bound to 127.0.0.1.
• Do not expose ports 5217 through 5226 through a router, tunnel, or reverse proxy.
• Run only agents you trust under the same Windows user.
• Never provide exchange or wallet secrets to the local agent.
• Begin with dry-run requests and small orders.
• Monitor orders and positions while validating a new agent.
• Keep both live provider settings off unless they are actively required.
• Disable the provider-specific live setting to stop new live actions.
• Disconnect the provider or close HyperionX for an immediate stop.
• Rotate HYPERIONX_RION_LOCAL_TOKEN if it might have been exposed.
• Review the Rion API audit records after every test session.

When capabilities advertise HPX-RION-V2, every POST requires a request ID and the in-process cache deduplicates the exact mutation for a limited period. Reuse the same ID only with the exact same execution body; a changed body needs a new ID. The cache is not durable across restart or guaranteed after expiry. Older builds can lack mutation idempotency entirely. If an outcome remains unknown, reconcile HyperionX and provider orders and positions before deciding whether another submission is safe. See Local Desktop API.

Action attempts are recorded under the path documented in Local Desktop API. An audit record proves that HyperionX processed an attempt; it does not prove that an exchange accepted or filled an order.

No MCP server is required. An MCP adapter can be added later as a convenience layer that maps standard MCP tools to these same HTTP endpoints without changing the underlying HyperionX policy.