openbroker 1.0.72 → 1.0.75

package/SKILL.md

@@ -4,7 +4,7 @@ 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.72", "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)"}]}}
+metadata: {"author": "monemetrics", "version": "1.0.75", "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:*)
 ---
 
@@ -127,8 +127,10 @@ HYPERLIQUID_NETWORK=mainnet
 ```bash
 openbroker account            # Balance, equity, margin
 openbroker account --orders   # Include open orders
+openbroker account --address 0xabc...  # Look up another account
 openbroker positions          # Open positions with PnL
 openbroker positions --coin ETH  # Specific coin
+openbroker positions --address 0xabc...  # Another account's positions
 ```
 
 ### Funding Rates
@@ -164,6 +166,7 @@ openbroker search --query ETH --type perp  # ETH perps only
 openbroker spot                   # Show all spot markets
 openbroker spot --coin PURR       # Show PURR market info
 openbroker spot --balances        # Show your spot balances
+openbroker spot --balances --address 0xabc...  # Another account's spot balances
 openbroker spot --top 20          # Top 20 by volume
 ```
 
@@ -172,6 +175,7 @@ openbroker spot --top 20          # Top 20 by volume
 openbroker fills                          # Recent fills
 openbroker fills --coin ETH               # ETH fills only
 openbroker fills --coin BTC --side buy --top 50
+openbroker fills --address 0xabc...       # Another account's fills
 ```
 
 ### Order History
@@ -181,17 +185,20 @@ openbroker orders --open                  # Currently open orders only
 openbroker orders --open --coin ETH       # Open orders for a specific coin
 openbroker orders --coin ETH --status filled
 openbroker orders --top 50
+openbroker orders --address 0xabc... --open  # Another account's open orders
 ```
 
 ### Order Status
 ```bash
 openbroker order-status --oid 123456789   # Check specific order
 openbroker order-status --oid 0x1234...   # By client order ID
+openbroker order-status --oid 123456789 --address 0xabc...  # On another account
 ```
 
 ### Fee Schedule
 ```bash
 openbroker fees                           # Fee tier, rates, and volume
+openbroker fees --address 0xabc...        # Another account's fees
 ```
 
 ### Candle Data (OHLCV)
@@ -521,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
 
@@ -773,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/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.72",
+  "version": "1.0.75",
   "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> =

package/scripts/core/ws.ts

@@ -0,0 +1,283 @@
+// WebSocket Manager for Hyperliquid real-time data
+// Wraps @nktkas/hyperliquid SubscriptionClient with event-driven API
+
+import { WebSocketTransport, SubscriptionClient } from '@nktkas/hyperliquid';
+import type { ISubscription } from '@nktkas/hyperliquid';
+import type {
+  AllMidsWsEvent,
+  OrderUpdatesWsEvent,
+  UserFillsWsEvent,
+  UserEventsWsEvent,
+} from '@nktkas/hyperliquid';
+import { isMainnet } from './config.js';
+
+// ── Event types ────────────────────────────────────────────────────
+
+export interface WsEventMap {
+  /** Mid prices for all assets updated */
+  allMids: { mids: Record<string, string> };
+  /** Order status changed (filled, canceled, rejected, etc.) */
+  orderUpdate: {
+    order: {
+      coin: string;
+      side: 'B' | 'A';
+      limitPx: string;
+      sz: string;
+      oid: number;
+      timestamp: number;
+      origSz: string;
+      cloid?: string;
+      reduceOnly?: boolean;
+    };
+    status: string;
+    statusTimestamp: number;
+  };
+  /** Trade fill received */
+  userFill: {
+    coin: string;
+    px: string;
+    sz: string;
+    side: 'B' | 'A';
+    time: number;
+    closedPnl: string;
+    fee: string;
+    oid: number;
+    crossed: boolean;
+  };
+  /** User event (fills, funding, liquidation, non-user cancels) */
+  userEvent: UserEventsWsEvent;
+  /** WebSocket connected */
+  connected: undefined;
+  /** WebSocket disconnected */
+  disconnected: { reason?: string };
+  /** WebSocket error */
+  error: { error: Error };
+}
+
+export type WsEventType = keyof WsEventMap;
+export type WsEventHandler<E extends WsEventType> = (data: WsEventMap[E]) => void;
+
+// ── Manager ────────────────────────────────────────────────────────
+
+export class WebSocketManager {
+  private transport: WebSocketTransport | null = null;
+  private client: SubscriptionClient | null = null;
+  private subscriptions: ISubscription[] = [];
+  private handlers = new Map<WsEventType, Set<Function>>();
+  private _connected = false;
+  private verbose: boolean;
+
+  constructor(verbose = false) {
+    this.verbose = verbose;
+  }
+
+  private log(...args: unknown[]) {
+    if (this.verbose) console.log('[WS]', ...args);
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  // ── Connection management ──────────────────────────────────────
+
+  async connect(): Promise<void> {
+    if (this.transport) return; // already connected
+
+    this.transport = new WebSocketTransport({
+      isTestnet: !isMainnet(),
+      resubscribe: true, // auto-resubscribe on reconnect
+    });
+
+    this.client = new SubscriptionClient({ transport: this.transport });
+
+    await this.transport.ready();
+    this._connected = true;
+    this.emit('connected', undefined);
+    this.log('Connected to', isMainnet() ? 'mainnet' : 'testnet');
+  }
+
+  async close(): Promise<void> {
+    for (const sub of this.subscriptions) {
+      try { await sub.unsubscribe(); } catch { /* ignore */ }
+    }
+    this.subscriptions = [];
+
+    if (this.transport) {
+      try { await this.transport.close(); } catch { /* ignore */ }
+      this.transport = null;
+      this.client = null;
+    }
+
+    this._connected = false;
+    this.emit('disconnected', { reason: 'manual close' });
+    this.log('Closed');
+  }
+
+  // ── Event system ───────────────────────────────────────────────
+
+  on<E extends WsEventType>(event: E, handler: WsEventHandler<E>): void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+  }
+
+  off<E extends WsEventType>(event: E, handler: WsEventHandler<E>): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+
+  private emit<E extends WsEventType>(event: E, data: WsEventMap[E]): void {
+    const set = this.handlers.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        handler(data);
+      } catch (err) {
+        this.log('Handler error:', err instanceof Error ? err.message : String(err));
+        this.emit('error' as E, { error: err instanceof Error ? err : new Error(String(err)) } as WsEventMap[E]);
+      }
+    }
+  }
+
+  removeAllListeners(): void {
+    this.handlers.clear();
+  }
+
+  // ── Subscription helpers ───────────────────────────────────────
+
+  private ensureClient(): SubscriptionClient {
+    if (!this.client) throw new Error('WebSocket not connected. Call connect() first.');
+    return this.client;
+  }
+
+  private trackSub(sub: ISubscription): ISubscription {
+    this.subscriptions.push(sub);
+    sub.failureSignal.addEventListener('abort', () => {
+      this.log('Subscription failed, removing from tracked list');
+      const idx = this.subscriptions.indexOf(sub);
+      if (idx >= 0) this.subscriptions.splice(idx, 1);
+    });
+    return sub;
+  }
+
+  // ── Market data subscriptions ──────────────────────────────────
+
+  /**
+   * Subscribe to mid prices for all assets. Fires on every price update.
+   */
+  async subscribeAllMids(): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.allMids((data: AllMidsWsEvent) => {
+      this.emit('allMids', { mids: data.mids });
+    });
+    return this.trackSub(sub);
+  }
+
+  // ── User subscriptions ────────────────────────────────────────
+
+  /**
+   * Subscribe to order lifecycle events (fill, cancel, reject, etc.).
+   * This is the most important subscription for trading automations.
+   */
+  async subscribeOrderUpdates(user: `0x${string}`): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.orderUpdates({ user }, (data: OrderUpdatesWsEvent) => {
+      for (const update of data) {
+        this.emit('orderUpdate', {
+          order: {
+            coin: update.order.coin,
+            side: update.order.side,
+            limitPx: update.order.limitPx,
+            sz: update.order.sz,
+            oid: update.order.oid,
+            timestamp: update.order.timestamp,
+            origSz: update.order.origSz,
+            cloid: update.order.cloid,
+            reduceOnly: update.order.reduceOnly,
+          },
+          status: update.status,
+          statusTimestamp: update.statusTimestamp,
+        });
+      }
+    });
+    return this.trackSub(sub);
+  }
+
+  /**
+   * Subscribe to trade fills for a user.
+   */
+  async subscribeUserFills(user: `0x${string}`): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.userFills({ user }, (data: UserFillsWsEvent) => {
+      if (data.isSnapshot) return; // skip initial snapshot
+      for (const fill of data.fills) {
+        this.emit('userFill', {
+          coin: fill.coin,
+          px: fill.px,
+          sz: fill.sz,
+          side: fill.side,
+          time: fill.time,
+          closedPnl: fill.closedPnl,
+          fee: fill.fee,
+          oid: fill.oid,
+          crossed: fill.crossed,
+        });
+      }
+    });
+    return this.trackSub(sub);
+  }
+
+  /**
+   * Subscribe to all user events (fills, funding, liquidations, non-user cancels).
+   * This is the only way to get liquidation alerts.
+   */
+  async subscribeUserEvents(user: `0x${string}`): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.userEvents({ user }, (data: UserEventsWsEvent) => {
+      this.emit('userEvent', data);
+    });
+    return this.trackSub(sub);
+  }
+
+  // ── Convenience: subscribe to all relevant feeds for an automation ──
+
+  /**
+   * Start all subscriptions needed for the automation runtime:
+   * - allMids (price feed)
+   * - orderUpdates (order lifecycle)
+   * - userFills (trade fills)
+   * - userEvents (liquidations, funding payments, system cancels)
+   */
+  async subscribeAll(user: `0x${string}`): Promise<void> {
+    await this.connect();
+    this.log('Subscribing to all feeds for', user);
+
+    await Promise.all([
+      this.subscribeAllMids(),
+      this.subscribeOrderUpdates(user),
+      this.subscribeUserFills(user),
+      this.subscribeUserEvents(user),
+    ]);
+
+    this.log('All subscriptions active');
+  }
+}
+
+// ── Singleton ──────────────────────────────────────────────────────
+
+let wsInstance: WebSocketManager | null = null;
+
+export function getWebSocket(verbose = false): WebSocketManager {
+  if (!wsInstance) {
+    wsInstance = new WebSocketManager(verbose);
+  }
+  return wsInstance;
+}
+
+export function resetWebSocket(): void {
+  if (wsInstance) {
+    wsInstance.close().catch(() => {});
+    wsInstance = null;
+  }
+}

package/scripts/info/account.ts

@@ -7,16 +7,20 @@ import { formatUsd, formatPercent, parseArgs } from '../core/utils.js';
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
   if (args.verbose) {
     client.verbose = true;
   }
 
-  const accountMode = await client.getAccountMode();
+  const lookupAddress = targetAddress?.toLowerCase() ?? client.address;
+  const isOtherAccount = !!targetAddress;
+
+  const accountMode = await client.getAccountMode(isOtherAccount ? lookupAddress : undefined);
 
   try {
-    const state = await client.getUserStateAll();
+    const state = await client.getUserStateAll(isOtherAccount ? lookupAddress : undefined);
 
     const margin = state.crossMarginSummary;
     const accountValue = parseFloat(margin.accountValue);
@@ -48,12 +52,19 @@ async function main() {
 
     const totalPnl = positions.reduce((sum, p) => sum + p.unrealizedPnl, 0);
 
+    // Fetch spot balances
+    const userParam = isOtherAccount ? lookupAddress : undefined;
+    const spotState = await client.getSpotBalances(userParam);
+    const spotBalances = (spotState?.balances ?? []).filter(b => parseFloat(b.total) > 0);
+
     // JSON output
     if (jsonOutput) {
       const result: Record<string, unknown> = {
-        address: client.address,
-        signingWallet: client.walletAddress,
-        walletType: client.isApiWallet ? 'api' : 'main',
+        address: lookupAddress,
+        ...(isOtherAccount ? {} : {
+          signingWallet: client.walletAddress,
+          walletType: client.isApiWallet ? 'api' : 'main',
+        }),
         accountMode,
         equity: accountValue,
         totalNotional,
@@ -62,10 +73,16 @@ async function main() {
         marginRatio: totalMarginUsed > 0 && accountValue > 0 ? totalMarginUsed / accountValue : 0,
         totalUnrealizedPnl: totalPnl,
         positions,
+        spotBalances: spotBalances.map(b => ({
+          coin: b.coin,
+          total: b.total,
+          hold: b.hold,
+          entryNtl: b.entryNtl,
+        })),
       };
 
       if (args.orders) {
-        const orders = await client.getOpenOrders();
+        const orders = await client.getOpenOrders(isOtherAccount ? lookupAddress : undefined);
         result.openOrders = orders.map(o => ({
           coin: o.coin,
           oid: o.oid,
@@ -85,11 +102,17 @@ async function main() {
     console.log('Open Broker - Account Info');
     console.log('==========================\n');
 
-    console.log('Wallet Configuration');
-    console.log('--------------------');
-    console.log(`Trading Account:  ${client.address}`);
-    console.log(`Signing Wallet:   ${client.walletAddress}`);
-    console.log(`Wallet Type:      ${client.isApiWallet ? 'API Wallet' : 'Main Wallet'}`);
+    if (isOtherAccount) {
+      console.log('Lookup Address');
+      console.log('--------------------');
+      console.log(`Address:          ${lookupAddress}`);
+    } else {
+      console.log('Wallet Configuration');
+      console.log('--------------------');
+      console.log(`Trading Account:  ${client.address}`);
+      console.log(`Signing Wallet:   ${client.walletAddress}`);
+      console.log(`Wallet Type:      ${client.isApiWallet ? 'API Wallet' : 'Main Wallet'}`);
+    }
 
     const modeLabel: Record<string, string> = {
       standard: 'Standard (separate balances per dex)',
@@ -99,22 +122,24 @@ async function main() {
     };
     console.log(`Account Mode:     ${modeLabel[accountMode] ?? accountMode}`);
 
-    // Check builder fee approval
-    const builderApproval = await client.getMaxBuilderFee();
-    console.log(`Builder Address:  ${client.builderAddress}`);
-    console.log(`Builder Fee:      ${client.builderFeeBps} bps`);
-    if (builderApproval) {
-      console.log(`Builder Approved: ✅ Yes (max: ${builderApproval})`);
-    } else {
-      console.log(`Builder Approved: ❌ No`);
-      console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
-    }
+    if (!isOtherAccount) {
+      // Check builder fee approval
+      const builderApproval = await client.getMaxBuilderFee();
+      console.log(`Builder Address:  ${client.builderAddress}`);
+      console.log(`Builder Fee:      ${client.builderFeeBps} bps`);
+      if (builderApproval) {
+        console.log(`Builder Approved: ✅ Yes (max: ${builderApproval})`);
+      } else {
+        console.log(`Builder Approved: ❌ No`);
+        console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
+      }
 
-    // Warn if API wallet setup looks misconfigured
-    if (!client.isApiWallet && accountValue === 0 && positions.length === 0) {
-      console.log('\n⚠️  No positions and $0 equity.');
-      console.log('   If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
-      console.log('   in ~/.openbroker/.env to the master account address (the wallet that holds funds).');
+      // Warn if API wallet setup looks misconfigured
+      if (!client.isApiWallet && accountValue === 0 && positions.length === 0) {
+        console.log('\n⚠️  No positions and $0 equity.');
+        console.log('   If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
+        console.log('   in ~/.openbroker/.env to the master account address (the wallet that holds funds).');
+      }
     }
     console.log('');
 
@@ -152,12 +177,29 @@ async function main() {
       console.log(`Total Unrealized PnL: ${formatUsd(totalPnl)}`);
     }
 
+    // Show spot balances
+    if (spotBalances.length > 0) {
+      console.log('\nSpot Balances');
+      console.log('-------------');
+      console.log('Token        | Total              | Hold               | Entry Value');
+      console.log('-------------|--------------------|--------------------|------------');
+
+      for (const b of spotBalances) {
+        const total = parseFloat(b.total);
+        const hold = parseFloat(b.hold);
+        const entry = parseFloat(b.entryNtl);
+        console.log(
+          `${b.coin.padEnd(12)} | ${total.toFixed(6).padStart(18)} | ${hold.toFixed(6).padStart(18)} | ${formatUsd(entry)}`
+        );
+      }
+    }
+
     // Show open orders if requested
     if (args.orders) {
       console.log('\nOpen Orders');
       console.log('-----------');
 
-      const orders = await client.getOpenOrders();
+      const orders = await client.getOpenOrders(isOtherAccount ? lookupAddress : undefined);
       if (orders.length === 0) {
         console.log('No open orders');
       } else {

package/scripts/info/fees.ts

@@ -24,13 +24,19 @@ async function main() {
     process.exit(0);
   }
 
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
+  const lookupAddress = targetAddress?.toLowerCase();
 
   console.log('Open Broker - Fee Schedule');
   console.log('=========================\n');
 
+  if (targetAddress) {
+    console.log(`Lookup: ${lookupAddress}\n`);
+  }
+
   try {
-    const fees = await client.getUserFees();
+    const fees = await client.getUserFees(lookupAddress);
 
     // Fee rates
     console.log('Fee Rates');

package/scripts/info/fills.ts

@@ -9,15 +9,17 @@ function printUsage() {
 Usage: openbroker fills [options]
 
 Options:
-  --coin <symbol>   Filter by coin (e.g. ETH, BTC)
-  --side <buy|sell>  Filter by side
-  --top <n>         Show last N fills (default: 20)
-  --help, -h        Show this help
+  --coin <symbol>      Filter by coin (e.g. ETH, BTC)
+  --side <buy|sell>    Filter by side
+  --top <n>            Show last N fills (default: 20)
+  --address <0x...>    Look up another account's fills
+  --help, -h           Show this help
 
 Examples:
   openbroker fills
   openbroker fills --coin ETH
   openbroker fills --coin BTC --side buy --top 50
+  openbroker fills --address 0xabc... --coin ETH
 `);
 }
 
@@ -33,10 +35,13 @@ async function main() {
   const filterSide = args.side as string | undefined;
   const top = parseInt(args.top as string) || 20;
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
+  const lookupAddress = targetAddress?.toLowerCase();
+
   try {
-    let fills = await client.getUserFills();
+    let fills = await client.getUserFills(lookupAddress);
 
     if (filterCoin) {
       fills = fills.filter(f => f.coin === normalizeCoin(filterCoin));
@@ -66,6 +71,10 @@ async function main() {
     console.log('Open Broker - Trade Fills');
     console.log('========================\n');
 
+    if (targetAddress) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
+
     if (fills.length === 0) {
       console.log('No fills found');
       return;

package/scripts/info/order-status.ts

@@ -9,12 +9,14 @@ function printUsage() {
 Usage: openbroker order-status --oid <order-id>
 
 Options:
-  --oid <id>    Order ID (number) or client order ID (hex string) — required
-  --help, -h    Show this help
+  --oid <id>          Order ID (number) or client order ID (hex string) — required
+  --address <0x...>   Look up order on another account
+  --help, -h          Show this help
 
 Examples:
   openbroker order-status --oid 123456789
   openbroker order-status --oid 0x1234abcd...
+  openbroker order-status --oid 123456789 --address 0xabc...
 `);
 }
 
@@ -34,13 +36,15 @@ async function main() {
   }
 
   const oid = oidArg.startsWith('0x') ? oidArg : parseInt(oidArg);
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
+  const lookupAddress = targetAddress?.toLowerCase();
 
   console.log('Open Broker - Order Status');
   console.log('=========================\n');
 
   try {
-    const result = await client.getOrderStatus(oid);
+    const result = await client.getOrderStatus(oid, lookupAddress);
 
     if (result.status === 'unknownOid') {
       console.log(`Order ${oidArg} not found`);

package/scripts/info/orders.ts

@@ -13,6 +13,7 @@ Options:
   --status <status>   Filter by status (filled, canceled, open, triggered, rejected, etc.)
   --open              Show only currently open orders
   --top <n>           Show last N orders (default: 20)
+  --address <0x...>   Look up another account's orders
   --help, -h          Show this help
 
 Examples:
@@ -21,6 +22,7 @@ Examples:
   openbroker orders --open --coin ETH
   openbroker orders --coin ETH --status filled
   openbroker orders --top 50
+  openbroker orders --address 0xabc... --open
 `);
 }
 
@@ -37,12 +39,15 @@ async function main() {
   const openOnly = args.open as boolean;
   const top = parseInt(args.top as string) || 20;
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
+  const lookupAddress = targetAddress?.toLowerCase();
+
   try {
     if (openOnly) {
       // Use the dedicated open orders endpoint
-      let openOrders = await client.getOpenOrders();
+      let openOrders = await client.getOpenOrders(lookupAddress);
 
       if (filterCoin) {
         openOrders = openOrders.filter(o => o.coin === normalizeCoin(filterCoin));
@@ -69,6 +74,10 @@ async function main() {
       console.log('Open Broker - Open Orders');
       console.log('=========================\n');
 
+      if (targetAddress) {
+        console.log(`Lookup: ${lookupAddress}\n`);
+      }
+
       if (openOrders.length === 0) {
         console.log('No open orders found');
         return;
@@ -106,7 +115,7 @@ async function main() {
       return;
     }
 
-    let orders = await client.getHistoricalOrders();
+    let orders = await client.getHistoricalOrders(lookupAddress);
 
     if (filterCoin) {
       orders = orders.filter(o => o.order.coin === normalizeCoin(filterCoin));
@@ -137,6 +146,10 @@ async function main() {
     console.log('Open Broker - Order History');
     console.log('==========================\n');
 
+    if (targetAddress) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
+
     if (orders.length === 0) {
       console.log('No orders found');
       return;

package/scripts/info/positions.ts

@@ -8,17 +8,21 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const filterCoin = args.coin as string | undefined;
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
   if (args.verbose) {
     client.verbose = true;
   }
 
+  const lookupAddress = targetAddress?.toLowerCase();
+  const isOtherAccount = !!targetAddress;
+
   try {
     const [state, mids, fundingHistory] = await Promise.all([
-      client.getUserStateAll(),
+      client.getUserStateAll(lookupAddress),
       client.getAllMids(),
-      client.getUserFunding(),
+      client.getUserFunding(lookupAddress),
     ]);
 
     const positions = state.assetPositions.filter(ap => {
@@ -69,9 +73,13 @@ async function main() {
     console.log('Open Broker - Positions');
     console.log('=======================\n');
 
+    if (isOtherAccount) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
+
     if (positions.length === 0) {
       console.log(filterCoin ? `No position in ${filterCoin}` : 'No open positions');
-      if (!filterCoin && !client.isApiWallet) {
+      if (!filterCoin && !isOtherAccount && !client.isApiWallet) {
         console.log('\n⚠️  If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
         console.log('   in ~/.openbroker/.env to the master account address.');
       }

package/scripts/info/spot.ts

@@ -8,6 +8,7 @@ interface Args {
   balances?: boolean;
   top?: number;
   verbose?: boolean;
+  address?: string;
 }
 
 function parseArgs(): Args {
@@ -21,6 +22,8 @@ function parseArgs(): Args {
       args.balances = true;
     } else if (arg === '--top' && process.argv[i + 1]) {
       args.top = parseInt(process.argv[++i], 10);
+    } else if (arg === '--address' && process.argv[i + 1]) {
+      args.address = process.argv[++i].toLowerCase();
     } else if (arg === '--verbose') {
       args.verbose = true;
     } else if (arg === '--help' || arg === '-h') {
@@ -30,11 +33,12 @@ Spot Markets - View Hyperliquid spot markets and balances
 Usage: npx tsx scripts/info/spot.ts [options]
 
 Options:
-  --coin <symbol>  Filter by coin symbol
-  --balances       Show your spot token balances
-  --top <n>        Show only top N markets by volume
-  --verbose        Show detailed output
-  --help           Show this help
+  --coin <symbol>      Filter by coin symbol
+  --balances           Show your spot token balances
+  --address <0x...>    Look up another account's spot balances (with --balances)
+  --top <n>            Show only top N markets by volume
+  --verbose            Show detailed output
+  --help               Show this help
 
 Examples:
   npx tsx scripts/info/spot.ts                  # Show all spot markets
@@ -80,9 +84,10 @@ async function main() {
 
   // Show balances
   if (args.balances) {
-    console.log(`Fetching spot balances for ${client.address}...\n`);
+    const lookupAddress = args.address ?? client.address;
+    console.log(`Fetching spot balances for ${lookupAddress}...\n`);
 
-    const balances = await client.getSpotBalances();
+    const balances = await client.getSpotBalances(args.address);
 
     if (!balances.balances || balances.balances.length === 0) {
       console.log('No spot token balances found.');