Skip to main content

​
Connection

​
WS /ws

Connect to the Hyperoru WebSocket server for real-time updates. Example connection 
wscat -c ws://localhost:8080/ws

const ws = new WebSocket("ws://localhost:8080/ws");
ws.onopen = () => console.log("Connected");
ws.onmessage = (e) => console.log(JSON.parse(e.data));

​
Message protocol

All WebSocket messages use JSON with a type field to identify the message kind. Client messages include an optional request_id for correlating responses. 
{
  "type": "message_type",
  "request_id": "optional-id",
  "data": {}
}

​
Client messages

​
connect

Authenticate and initialize the WebSocket session. 
{
  "type": "connect",
  "request_id": "1",
  "data": {
    "session_token": "abc123"
  }
}

​
bootstrap

Request initial state data after connecting. 
{
  "type": "bootstrap",
  "request_id": "2"
}
Server response 
{
  "type": "bootstrap",
  "request_id": "2",
  "data": {
    "accounts": [{ "id": 1, "name": "Main Account" }],
    "positions": [],
    "active_orders": []
  }
}

​
subscribe

Subscribe to specific event channels.
​
channels
string[]
required
Channels to subscribe to: trades, positions, model_chat, asset_curve.
{
  "type": "subscribe",
  "request_id": "3",
  "data": {
    "channels": ["trades", "positions", "asset_curve"]
  }
}

​
switch_user

Switch the active user context. 
{
  "type": "switch_user",
  "request_id": "4",
  "data": {
    "user_id": 1
  }
}

​
switch_account

Switch the active account context for receiving updates. 
{
  "type": "switch_account",
  "request_id": "5",
  "data": {
    "account_id": 1
  }
}

​
get_snapshot

Request a point-in-time snapshot of account state. 
{
  "type": "get_snapshot",
  "request_id": "6",
  "data": {
    "account_id": 1
  }
}
Server response 
{
  "type": "snapshot",
  "request_id": "6",
  "data": {
    "equity": 10000.0,
    "positions": [
      { "symbol": "BTC", "side": "long", "size": 0.05, "unrealized_pnl": 75.0 }
    ]
  }
}

​
get_asset_curve

Request asset curve data via WebSocket. 
{
  "type": "get_asset_curve",
  "request_id": "7",
  "data": {
    "account_id": 1,
    "timeframe": "7d"
  }
}

​
place_order

Place a trading order through the WebSocket connection. 
{
  "type": "place_order",
  "request_id": "8",
  "data": {
    "account_id": 1,
    "symbol": "BTC",
    "side": "buy",
    "size": 0.01,
    "order_type": "market"
  }
}

​
ping

Keep-alive heartbeat. Server responds with pong. 
{
  "type": "ping"
}
Server response 
{
  "type": "pong"
}

​
Broadcast events

The server pushes these events to subscribed clients in real time.

​
trade_update

Fired when a trade is executed, updated, or closed. 
{
  "type": "trade_update",
  "data": {
    "trade_id": 42,
    "account_id": 1,
    "symbol": "BTC",
    "side": "buy",
    "status": "filled",
    "price": 68500.0,
    "size": 0.01,
    "pnl": null,
    "timestamp": "2026-04-09T12:00:00Z"
  }
}

​
position_update

Fired when a position changes (opened, modified, closed). 
{
  "type": "position_update",
  "data": {
    "account_id": 1,
    "symbol": "BTC",
    "side": "long",
    "size": 0.05,
    "entry_price": 67000.0,
    "mark_price": 68500.0,
    "unrealized_pnl": 75.0,
    "timestamp": "2026-04-09T12:00:05Z"
  }
}

​
model_chat_update

Fired when an AI model produces a trading decision or reasoning update. 
{
  "type": "model_chat_update",
  "data": {
    "decision_id": "dec-001",
    "account_id": 1,
    "symbol": "BTC",
    "decision": "buy",
    "reasoning": "RSI oversold at 28, strong support at 67000...",
    "timestamp": "2026-04-09T12:00:00Z"
  }
}

​
asset_curve_update

Fired periodically with updated portfolio value data. 
{
  "type": "asset_curve_update",
  "data": {
    "account_id": 1,
    "timestamp": "2026-04-09T12:00:00Z",
    "equity": 10075.0,
    "daily_pnl": 75.0,
    "daily_return_pct": 0.75
  }
}