openbroker 1.0.73 → 1.0.79

package/SKILL.md

@@ -4,8 +4,8 @@ description: Hyperliquid trading plugin with background position monitoring and
 license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.0.73", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
-allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_twap_cancel ob_twap_status ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
+metadata: {"author": "monemetrics", "version": "1.0.79", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
+allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_spot_buy ob_spot_sell ob_twap ob_twap_cancel ob_twap_status ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI
@@ -528,11 +528,11 @@ To view bundled examples and their config schemas:
 openbroker auto examples    # List examples with config fields
 ```
 
-Available examples: `dca`, `grid`, `funding-arb`, `mm-spread`, `mm-maker`
+Available examples: `dca`, `grid`, `funding-arb`, `mm-spread`, `mm-maker`, `price-alert`
 
 ### How Automations Work
 
-An automation is a `.ts` file that exports a default function. The function receives an `AutomationAPI` with the full Hyperliquid client, typed event subscriptions, persistent state, and a logger. The runtime polls Hyperliquid every 10s (configurable) and dispatches events when changes are detected.
+An automation is a `.ts` file that exports a default function. The function receives an `AutomationAPI` with the full Hyperliquid client, typed event subscriptions, persistent state, and a logger. The runtime connects a WebSocket for real-time price and order events, with REST polling every 30s as a heartbeat for position/margin data. Use `--no-ws` to disable WebSocket and fall back to pure REST polling (every 10s).
 
 ### Writing an Automation
 
@@ -780,18 +780,66 @@ api.on('margin_warning', async ({ marginUsedPct, equity }) => {
 });
 ```
 
+#### `order_update` — Real-time order lifecycle (WebSocket)
+Fires instantly when any order changes status: `open`, `filled`, `canceled`, `triggered`, `rejected`, `marginCanceled`, `liquidatedCanceled`, `badAloPxRejected`, and 20+ other statuses. Requires WebSocket (enabled by default).
+
+**Payload:** `{ coin: string, oid: number, side: 'buy' | 'sell', size: number, price: number, origSize: number, status: string, statusTimestamp: number }`
+
+**Example:**
+```typescript
+api.on('order_update', async ({ coin, oid, status, side, size, price }) => {
+  if (status === 'filled') {
+    api.log.info(`Order ${oid} filled: ${side} ${size} ${coin} @ $${price}`);
+  } else if (status === 'canceled' || status.includes('Rejected')) {
+    api.log.warn(`Order ${oid} ${status}: ${coin}`);
+  }
+});
+```
+
+#### `liquidation` — Liquidation alert (WebSocket only)
+Fires when the account is liquidated. This event is **only available via WebSocket** — there is no REST polling equivalent.
+
+**Payload:** `{ lid: number, liquidator: string, liquidatedUser: string, liquidatedNtlPos: number, liquidatedAccountValue: number }`
+
+**Example:**
+```typescript
+api.on('liquidation', async ({ liquidatedNtlPos, liquidatedAccountValue }) => {
+  await api.publish(
+    `LIQUIDATED: $${liquidatedNtlPos.toFixed(2)} notional, account value: $${liquidatedAccountValue.toFixed(2)}`,
+    { name: 'liquidation-alert' },
+  );
+});
+```
+
+### WebSocket Real-Time Data
+
+Automations use **WebSocket by default** for real-time market and account events. The runtime subscribes to:
+- **allMids** — price updates for all assets (drives `price_change` events in real-time)
+- **orderUpdates** — order lifecycle events (drives `order_update` and `order_filled`)
+- **userFills** — trade fill details with PnL and fees
+- **userEvents** — liquidation alerts, funding payments, system cancellations
+
+REST polling continues as a **heartbeat** (every 60s by default) for position/margin/funding events that aren't covered by WebSocket. If the WebSocket connection fails, the runtime falls back to full REST polling (every 10s) automatically.
+
+To disable WebSocket (pure REST polling):
+```bash
+openbroker auto run my-strategy.ts --no-ws
+```
+
 ### Choosing the Right Event — Quick Guide
 
 | Use case | Best event | Why |
 |----------|-----------|-----|
 | Alert when price crosses a fixed level | `tick` | Fires every poll — no minimum change threshold |
-| React to price momentum/volatility | `price_change` | Provides relative change data between polls |
+| React to price momentum/volatility | `price_change` | Real-time via WebSocket, provides relative change data |
 | Funding rate strategy | `funding_update` | Gives annualized rate directly |
 | Auto TP/SL on new positions | `position_opened` | Fires exactly when a new position appears |
 | Log when positions close | `position_closed` | Fires when position disappears |
 | Track position scaling | `position_changed` | Fires on size changes only |
 | Risk management — PnL spikes | `pnl_threshold` | Only fires on large moves (≥5% of position value) |
 | Risk management — margin | `margin_warning` | Fires at 80%+ margin usage |
+| React instantly to order fills/rejects | `order_update` | Real-time via WebSocket — sub-second latency |
+| Liquidation alerts | `liquidation` | WebSocket only — no REST equivalent |
 | Periodic task (DCA, rebalance) | `api.every(ms, fn)` | Better than tick for longer intervals |
 
 ### Client Methods Available

package/bin/cli.ts

@@ -47,6 +47,9 @@ const commands: Record<string, { script: string; description: string }> = {
   'scale': { script: 'operations/scale.ts', description: 'Scale in/out orders' },
   'bracket': { script: 'operations/bracket.ts', description: 'Bracket order (entry + TP + SL)' },
   'chase': { script: 'operations/chase.ts', description: 'Chase order with ALO' },
+  'spot-buy': { script: 'operations/spot-order.ts', description: 'Spot buy order' },
+  'spot-sell': { script: 'operations/spot-order.ts', description: 'Spot sell order' },
+  'spot-order': { script: 'operations/spot-order.ts', description: 'Spot order (market or limit)' },
 
   // Automations
   'auto': { script: 'auto/cli.ts', description: 'Run/manage trading automations' },
@@ -88,6 +91,11 @@ Trading Commands:
   tpsl                 Set TP/SL on existing position
   cancel               Cancel orders
 
+Spot Trading:
+  spot-buy             Spot buy order
+  spot-sell            Spot sell order
+  spot-order           Spot order (market or limit, specify --side)
+
 Advanced Execution:
   twap                 Native TWAP order (exchange-managed)
   twap-cancel          Cancel a running TWAP order
@@ -167,6 +175,14 @@ function main() {
     runScript(commands['market'].script, ['--side', 'sell', ...commandArgs]);
     return;
   }
+  if (command === 'spot-buy') {
+    runScript(commands['spot-order'].script, ['--side', 'buy', ...commandArgs]);
+    return;
+  }
+  if (command === 'spot-sell') {
+    runScript(commands['spot-order'].script, ['--side', 'sell', ...commandArgs]);
+    return;
+  }
 
   // Handle version
   if (command === '--version' || command === '-v') {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openbroker",
   "name": "OpenBroker — Hyperliquid Trading",
-  "version": "1.0.73",
+  "version": "1.0.79",
   "description": "Trade on Hyperliquid DEX with background position monitoring",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.73",
+  "version": "1.0.79",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {

package/scripts/auto/cli.ts

@@ -104,10 +104,11 @@ async function runCommand(args: Record<string, string | boolean>, positional: st
   const scriptPath = exampleName ? resolveExamplePath(exampleName) : resolveScriptPath(scriptName!);
   const dryRun = args.dry === true;
   const verbose = args.verbose === true;
-  const pollIntervalMs = args.poll ? parseInt(String(args.poll), 10) : 10_000;
+  const useWebSocket = args['no-ws'] !== true;
+  const pollIntervalMs = args.poll ? parseInt(String(args.poll), 10) : undefined;
   const id = args.id ? String(args.id) : undefined;
 
-  if (isNaN(pollIntervalMs) || pollIntervalMs < 1000) {
+  if (pollIntervalMs !== undefined && (isNaN(pollIntervalMs) || pollIntervalMs < 1000)) {
     console.error('Error: --poll must be at least 1000ms');
     process.exit(1);
   }
@@ -118,6 +119,7 @@ async function runCommand(args: Record<string, string | boolean>, positional: st
     dryRun,
     verbose,
     pollIntervalMs,
+    useWebSocket,
     initialState: Object.keys(initialState).length > 0 ? initialState : undefined,
   });
 

package/scripts/auto/examples/price-alert.ts

@@ -0,0 +1,96 @@
+// Price Alert — Real-time price monitoring via WebSocket
+// Showcases WebSocket-driven price_change and order_update events
+
+import type { AutomationAPI, AutomationConfig } from '../types.js';
+
+export const config: AutomationConfig = {
+  description: 'Real-time price alerts via WebSocket — log price moves and order updates',
+  fields: {
+    coin:      { type: 'string',  description: 'Asset to monitor', default: 'BTC' },
+    threshold: { type: 'number',  description: 'Min price change % to alert on', default: 0.1 },
+    above:     { type: 'number',  description: 'Alert when price goes above this level (0 = disabled)', default: 0 },
+    below:     { type: 'number',  description: 'Alert when price goes below this level (0 = disabled)', default: 0 },
+  },
+};
+
+export default function priceAlert(api: AutomationAPI) {
+  const COIN = api.state.get<string>('coin', 'BTC')!;
+  const THRESHOLD = api.state.get<number>('threshold', 0.1)!;
+  const ABOVE = api.state.get<number>('above', 0)!;
+  const BELOW = api.state.get<number>('below', 0)!;
+
+  let alertCount = 0;
+  let lastAlertPrice = 0;
+  let aboveTriggered = false;
+  let belowTriggered = false;
+
+  api.onStart(() => {
+    api.log.info(`Monitoring ${COIN} via WebSocket`);
+    api.log.info(`Threshold: ${THRESHOLD}% change`);
+    if (ABOVE > 0) api.log.info(`Alert above: $${ABOVE}`);
+    if (BELOW > 0) api.log.info(`Alert below: $${BELOW}`);
+  });
+
+  // Real-time price changes via WebSocket
+  api.on('price_change', ({ coin, oldPrice, newPrice, changePct }) => {
+    if (coin !== COIN) return;
+
+    // Threshold alerts — fires when move exceeds configured %
+    if (Math.abs(changePct) >= THRESHOLD) {
+      const dir = changePct > 0 ? 'UP' : 'DOWN';
+      api.log.info(`${COIN} ${dir} ${changePct.toFixed(3)}%: $${oldPrice.toFixed(2)} -> $${newPrice.toFixed(2)}`);
+      alertCount++;
+      lastAlertPrice = newPrice;
+    }
+
+    // Level alerts — fires once when price crosses a level, resets when it crosses back
+    if (ABOVE > 0) {
+      if (newPrice >= ABOVE && !aboveTriggered) {
+        aboveTriggered = true;
+        api.log.info(`${COIN} ABOVE $${ABOVE}: now $${newPrice.toFixed(2)}`);
+        api.publish(`${COIN} broke above $${ABOVE} — now $${newPrice.toFixed(2)}`, { name: 'price-alert' });
+      } else if (newPrice < ABOVE) {
+        aboveTriggered = false;
+      }
+    }
+
+    if (BELOW > 0) {
+      if (newPrice <= BELOW && !belowTriggered) {
+        belowTriggered = true;
+        api.log.info(`${COIN} BELOW $${BELOW}: now $${newPrice.toFixed(2)}`);
+        api.publish(`${COIN} dropped below $${BELOW} — now $${newPrice.toFixed(2)}`, { name: 'price-alert' });
+      } else if (newPrice > BELOW) {
+        belowTriggered = false;
+      }
+    }
+  });
+
+  // Real-time order lifecycle via WebSocket
+  api.on('order_update', ({ coin, oid, side, size, price, status }) => {
+    if (status === 'filled') {
+      api.log.info(`ORDER FILLED: ${side.toUpperCase()} ${size} ${coin} @ $${price.toFixed(2)} (oid: ${oid})`);
+    } else if (status === 'canceled' || status.includes('Canceled') || status.includes('Rejected')) {
+      api.log.warn(`ORDER ${status.toUpperCase()}: ${side} ${size} ${coin} @ $${price.toFixed(2)} (oid: ${oid})`);
+    }
+  });
+
+  // Liquidation alerts via WebSocket
+  api.on('liquidation', ({ liquidatedNtlPos, liquidatedAccountValue }) => {
+    api.log.error(`LIQUIDATION: $${liquidatedNtlPos.toFixed(2)} notional, account value: $${liquidatedAccountValue.toFixed(2)}`);
+    api.publish(
+      `LIQUIDATED: $${liquidatedNtlPos.toFixed(2)} notional, account value: $${liquidatedAccountValue.toFixed(2)}`,
+      { name: 'liquidation-alert' },
+    );
+  });
+
+  // Periodic summary via REST heartbeat
+  api.on('tick', ({ pollCount }) => {
+    if (pollCount % 10 === 0 && alertCount > 0) {
+      api.log.info(`Summary: ${alertCount} alerts fired, last price: $${lastAlertPrice.toFixed(2)}`);
+    }
+  });
+
+  api.onStop(() => {
+    api.log.info(`Stopped. Total alerts: ${alertCount}`);
+  });
+}

package/scripts/auto/runtime.ts

@@ -1,4 +1,5 @@
 // Automation Runtime — loads scripts, polls market data, dispatches events
+// Supports real-time WebSocket feeds with REST polling as fallback heartbeat
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import path from 'path';
@@ -9,6 +10,7 @@ import {
   roundPrice, roundSize, sleep, normalizeCoin,
   formatUsd, formatPercent, annualizeFundingRate,
 } from '../core/utils.js';
+import { WebSocketManager } from '../core/ws.js';
 import { AutomationEventBus } from './events.js';
 import { loadAutomation } from './loader.js';
 import { registerAutomation, unregisterAutomation, markAutomationError, getRegisteredAutomations as getRegisteredFromFile } from './registry.js';
@@ -233,6 +235,13 @@ export interface RuntimeOptions {
   hooksToken?: string;
   /** Pre-seed state before the factory function runs (e.g. from --set key=value) */
   initialState?: Record<string, unknown>;
+  /**
+   * Enable WebSocket for real-time events (allMids, orderUpdates, userFills, userEvents).
+   * When enabled, REST polling interval is relaxed to a heartbeat (default 60s).
+   * Falls back gracefully to polling if WebSocket connection fails.
+   * @default true
+   */
+  useWebSocket?: boolean;
 }
 
 /** Registry of all running automations */
@@ -254,12 +263,16 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     scriptPath,
     dryRun = false,
     verbose = false,
-    pollIntervalMs = 10_000,
     gatewayPort,
     hooksToken,
     initialState,
+    useWebSocket = true,
   } = options;
 
+  // When WebSocket is enabled, REST poll becomes a heartbeat (30s default)
+  // When disabled, use the original 10s polling interval
+  const pollIntervalMs = options.pollIntervalMs ?? (useWebSocket ? 30_000 : 10_000);
+
   const id = options.id || path.basename(scriptPath, '.ts');
 
   if (registry.has(id)) {
@@ -317,7 +330,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     }
   }
 
-  // Polling state
+  // Polling state (declared early so WebSocket handlers can reference)
   let previousSnapshot: AutomationSnapshot | null = null;
   let pollCount = 0;
   let eventsEmitted = 0;
@@ -333,6 +346,110 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     }
   }
 
+  // ── WebSocket setup ─────────────────────────────────────────────
+  let ws: WebSocketManager | null = null;
+  let wsConnected = false;
+  // Track latest prices from WebSocket for real-time price_change events
+  let wsPrices = new Map<string, number>();
+
+  if (useWebSocket) {
+    try {
+      ws = new WebSocketManager(verbose);
+
+      // Wire WebSocket events to the automation event bus
+      ws.on('allMids', ({ mids }) => {
+        const now = Date.now();
+        for (const [coin, mid] of Object.entries(mids)) {
+          const newPrice = parseFloat(mid);
+          if (isNaN(newPrice) || newPrice === 0) continue;
+          const oldPrice = wsPrices.get(coin);
+          wsPrices.set(coin, newPrice);
+
+          if (oldPrice !== undefined && oldPrice !== 0 && eventBus.has('price_change')) {
+            const changePct = ((newPrice - oldPrice) / oldPrice) * 100;
+            if (Math.abs(changePct) >= 0.01) {
+              eventBus.emit('price_change', { coin, oldPrice, newPrice, changePct })
+                .then(errors => { if (errors.length) handleErrors(errors); });
+              eventsEmitted++;
+            }
+          }
+        }
+      });
+
+      ws.on('orderUpdate', (update) => {
+        if (eventBus.has('order_update')) {
+          eventBus.emit('order_update', {
+            coin: update.order.coin,
+            oid: update.order.oid,
+            side: update.order.side === 'B' ? 'buy' : 'sell',
+            size: parseFloat(update.order.sz),
+            price: parseFloat(update.order.limitPx),
+            origSize: parseFloat(update.order.origSz),
+            status: update.status,
+            statusTimestamp: update.statusTimestamp,
+          }).then(errors => { if (errors.length) handleErrors(errors); });
+          eventsEmitted++;
+        }
+
+        // Also emit order_filled for backward compatibility
+        if (update.status === 'filled' && eventBus.has('order_filled')) {
+          eventBus.emit('order_filled', {
+            coin: update.order.coin,
+            oid: update.order.oid,
+            side: update.order.side === 'B' ? 'buy' : 'sell',
+            size: parseFloat(update.order.sz),
+            price: parseFloat(update.order.limitPx),
+          }).then(errors => { if (errors.length) handleErrors(errors); });
+          eventsEmitted++;
+        }
+      });
+
+      ws.on('userFill', (fill) => {
+        // userFill events are already covered by order_update with status=filled
+        // But this provides the realized PnL and fee data that order_update doesn't have
+        log.debug(`Fill: ${fill.side === 'B' ? 'BUY' : 'SELL'} ${fill.sz} ${fill.coin} @ ${fill.px} (PnL: ${fill.closedPnl})`);
+      });
+
+      ws.on('userEvent', (event) => {
+        // Handle liquidation events — only available through WebSocket
+        if ('liquidation' in event && eventBus.has('liquidation')) {
+          const liq = event.liquidation;
+          eventBus.emit('liquidation', {
+            lid: liq.lid,
+            liquidator: liq.liquidator,
+            liquidatedUser: liq.liquidated_user,
+            liquidatedNtlPos: parseFloat(liq.liquidated_ntl_pos),
+            liquidatedAccountValue: parseFloat(liq.liquidated_account_value),
+          }).then(errors => { if (errors.length) handleErrors(errors); });
+          eventsEmitted++;
+        }
+      });
+
+      ws.on('error', ({ error }) => {
+        log.warn(`WebSocket error: ${error.message}`);
+      });
+
+      ws.on('disconnected', () => {
+        wsConnected = false;
+        log.warn('WebSocket disconnected — falling back to REST polling');
+      });
+
+      ws.on('connected', () => {
+        wsConnected = true;
+        log.info('WebSocket connected — real-time events active');
+      });
+
+      // Connect and subscribe
+      const userAddress = rawClient.address as `0x${string}`;
+      await ws.subscribeAll(userAddress);
+      log.info('WebSocket subscriptions active (allMids, orderUpdates, userFills, userEvents)');
+    } catch (err) {
+      log.warn(`WebSocket setup failed: ${err instanceof Error ? err.message : String(err)} — using REST polling only`);
+      ws = null;
+      wsConnected = false;
+    }
+  }
+
   async function poll() {
     if (isPolling || stopped) return;
     isPolling = true;
@@ -348,8 +465,8 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
       eventsEmitted++;
 
       if (previousSnapshot) {
-        // Price changes
-        if (eventBus.has('price_change')) {
+        // Price changes (skip when WebSocket is handling real-time prices)
+        if (eventBus.has('price_change') && !wsConnected) {
           for (const [coin, newPrice] of snapshot.prices) {
             const oldPrice = previousSnapshot.prices.get(coin);
             if (oldPrice === undefined || oldPrice === 0) continue;
@@ -485,7 +602,8 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
   }
 
   // Start polling
-  log.info(`Started (poll every ${pollIntervalMs / 1000}s, dry=${dryRun})`);
+  const wsLabel = wsConnected ? ', ws=on' : (useWebSocket ? ', ws=failed' : '');
+  log.info(`Started (poll every ${pollIntervalMs / 1000}s, dry=${dryRun}${wsLabel})`);
   const timer = setInterval(poll, pollIntervalMs);
 
   // Initial poll to seed state
@@ -497,6 +615,13 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     stopped = true;
     clearInterval(timer);
 
+    // Close WebSocket
+    if (ws) {
+      ws.removeAllListeners();
+      await ws.close();
+      ws = null;
+    }
+
     for (const hook of stopHooks) {
       try { await hook(); } catch (err) {
         log.error(`onStop hook error: ${err instanceof Error ? err.message : String(err)}`);

package/scripts/auto/types.ts

@@ -33,7 +33,9 @@ export type AutomationEventType =
   | 'position_changed'
   | 'pnl_threshold'
   | 'margin_warning'
-  | 'order_filled';
+  | 'order_filled'
+  | 'order_update'
+  | 'liquidation';
 
 export interface AutomationEventPayloads {
   tick: { timestamp: number; pollCount: number };
@@ -45,6 +47,25 @@ export interface AutomationEventPayloads {
   pnl_threshold: { coin: string; unrealizedPnl: number; changePct: number; positionValue: number };
   margin_warning: { marginUsedPct: number; equity: number; marginUsed: number };
   order_filled: { coin: string; oid: number; side: 'buy' | 'sell'; size: number; price: number };
+  /** Real-time order lifecycle event via WebSocket (filled, canceled, rejected, triggered, etc.) */
+  order_update: {
+    coin: string;
+    oid: number;
+    side: 'buy' | 'sell';
+    size: number;
+    price: number;
+    origSize: number;
+    status: string;
+    statusTimestamp: number;
+  };
+  /** Liquidation event via WebSocket — only source for liquidation alerts */
+  liquidation: {
+    lid: number;
+    liquidator: string;
+    liquidatedUser: string;
+    liquidatedNtlPos: number;
+    liquidatedAccountValue: number;
+  };
 }
 
 export type AutomationEventHandler<E extends AutomationEventType> =