openbroker 1.9.3 → 1.9.4

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.9.3] - 2026-06-23
+
+### Changed
+- Made automation reads WebSocket-first for mids, asset contexts, account state, spot balances, per-dex open orders, and lazily subscribed L2 books, with transparent REST fallback.
+- Activated the existing all-dex context, all-dex clearinghouse, and spot-state subscriptions before strategy `onStart` hooks.
+- Decoupled `api.every()` from REST snapshot polling. Short `--poll` values now control the disconnected fallback cadence; connected runtimes reconcile over REST at most once per minute.
+- Cached and request-de-duplicated the REST-only predicted-funding feed for 60 seconds, retaining the last good value through transient rate limits.
+- Limited automation startup metadata to the native universe and deferred HIP-3 metadata until a prefixed market is actually referenced.
+
+### Added
+- Added realtime-cache tests covering live market/account reads, lazy order-book seeding, and disconnected REST fallback.
+
 ## [1.9.2] - 2026-06-22
 
 ### Breaking

package/README.md

@@ -764,6 +764,22 @@ openbroker approve-builder --max-fee "0.05%"  # Custom max fee
 | `--builder` | Custom builder address (advanced) | Open Broker |
 | `--verbose` | Show debug output | — |
 
+## Automation Runtime
+
+Run audited TypeScript automations with required runtime guardrails:
+
+```bash
+openbroker auto run ./my-automation.ts --id my-auto --set coin=HYPE
+```
+
+WebSocket mode is enabled by default. Before an automation's `onStart` hooks run, OpenBroker subscribes to live mids, all-dex asset contexts, all-dex account state, spot balances, per-dex open-order snapshots, order updates, fills, and user events. L2 books are subscribed lazily per requested coin.
+
+Existing strategies continue to use `api.client`. Inside the automation runtime, `getAllMids()`, `getMetaAndAssetCtxs()`, `getUserState()`, `getUserStateAll()`, `getSpotBalances()`, `getOpenOrders()`, and `getL2Book()` read the live WebSocket cache first and automatically fall back to REST when the socket is unavailable or a feed has not seeded. `getPredictedFundings()` has no socket equivalent, so it is request-de-duplicated, cached for 60 seconds, and serves the last successful value through transient rate limits.
+
+`api.every(intervalMs, handler)` uses an independent scheduler and does not trigger a REST snapshot. `--poll` controls the disconnected REST fallback cadence; while WebSocket is healthy, full REST reconciliation runs no more than once per minute even when an older launch command passes a shorter value such as `--poll 5000`. Use `--no-ws` only when you intentionally need REST-only behavior.
+
+Every automation must export `guardrails` plus its default factory. See [SKILL.md](./SKILL.md) for the complete schema, WebSocket event model, and runtime enforcement rules.
+
 ## OpenClaw Plugin
 
 OpenBroker ships as an [OpenClaw](https://openclaw.ai) plugin. When installed via OpenClaw, it registers structured agent tools and a background position watcher — no Bash wrappers needed.

package/SKILL.md

@@ -213,7 +213,7 @@ Run flags:
 |---|---|
 | `--set key=value` | Repeatable typed config values |
 | `--id <name>` | Stable automation ID |
-| `--poll <ms>` | Poll interval, minimum 1000 ms |
+| `--poll <ms>` | REST fallback interval, minimum 1000 ms. While WebSocket is healthy, REST reconciliation is capped at once per minute. |
 | `--dry` | Intercept write methods |
 | `--no-ws` | Disable WebSocket and rely on REST polling |
 | `--allow-sleep` | Do not request OS sleep inhibition |
@@ -279,6 +279,23 @@ Treat `api.client` as the only supported execution path. Automation files are tr
 
 Core events include `tick`, `price_change`, `funding_update`, `position_opened`, `position_closed`, `position_changed`, `pnl_threshold`, `margin_warning`, `order_filled`, `order_update`, and `liquidation`.
 
+### WebSocket-first runtime
+
+WebSocket mode is enabled by default. Before `onStart`, the runtime subscribes to:
+
+- `allMids` for instant perp and spot prices;
+- `allDexsAssetCtxs` for funding, mark, oracle, open-interest, and premium changes;
+- `allDexsClearinghouseState` plus `spotState` for positions, margin, collateral, and balances;
+- `openOrders` for the native dex and every active HIP-3 dex so guardrail order-count checks stay live;
+- `orderUpdates`, `userFills`, and `userEvents` for order lifecycle, fills, funding payments, and liquidations;
+- `l2Book` lazily, the first time an automation requests a book for a coin.
+
+The normal `api.client` read methods are WebSocket-aware inside automations. `getAllMids()`, `getMetaAndAssetCtxs()`, `getUserState()`, `getUserStateAll()`, `getSpotBalances()`, `getOpenOrders()`, and `getL2Book()` return fresh socket data when available and transparently fall back to REST when the socket is disconnected, a subscription has not seeded yet, or live market data is stale. Automation code should keep using `api.client`; do not import a second exchange SDK or create a second socket.
+
+`api.every(intervalMs, handler)` runs on an independent scheduler and no longer causes a REST snapshot. `--poll` controls the disconnected fallback cadence. While the socket is healthy, the runtime performs a REST reconciliation no more than once per minute, even when an older launch command passes `--poll 5000`. Predicted cross-venue funding has no equivalent socket feed, so `getPredictedFundings()` is de-duplicated, cached for 60 seconds, and serves the last good value if a refresh is temporarily rate-limited.
+
+Use `--no-ws` only for debugging or networks that cannot maintain WebSockets. In that mode, `--poll` is the active REST cadence and event latency follows it.
+
 ### Monitoring and dashboard
 
 `openbroker-monitoring` is optional but useful for long-running automations, live debugging, and post-run inspection.
@@ -300,7 +317,7 @@ These matter more than boilerplate:
 
 1. **Model the strategy as a state machine.** Persist flags, streaks, targets, and recovery state with `api.state`; handlers can fire repeatedly and processes can restart.
 2. **Use hysteresis, not one-print decisions.** Confirmation loops, separate enter/exit thresholds, and debounce logic prevent churn from noisy funding or tiny price moves.
-3. **Use the freshest correct signal.** For funding strategies, prefer `getPredictedFundings()` when available; if you fall back to instantaneous funding from metadata, ensure the metadata cache is refreshed so the signal does not freeze after startup.
+3. **Use the freshest correct signal.** Instantaneous funding and prices are WebSocket-backed by default. Prefer `getPredictedFundings()` for cross-venue forecasts; the runtime refreshes that REST-only signal at most once per minute and retains the last good value through transient rate limits.
 4. **Price the flip, not just the signal.** Before closing and later reopening a carry, compare expected hold cost with round-trip trading cost. The HYPE carry automation counts maker fees across both legs plus builder fees before deciding whether a mildly negative funding window is worth exiting.
 5. **Respect settlement timing.** If the current predicted funding is still positive, a close right before hourly settlement can be economically wrong even when the broader signal weakened. Add a settlement-proximity guard when the strategy depends on funding capture.
 6. **Sequence multi-leg hedges deliberately.** For spot-long / perp-short carry, build spot first, then short only up to spot-backed exposure; unwind spot first, then close the short reduce-only. Recover accidental one-sided exposure explicitly instead of pretending it cannot happen.
@@ -312,7 +329,7 @@ These matter more than boilerplate:
 Additional practical caveats:
 
 - Positive-funding carry and negative-funding carry are not automatically symmetric. If the hedge requires short spot and the client/runtime cannot express that safely, do not invent an unhedged mirror trade.
-- `funding_update` fires for many assets every poll; filter by coin early.
+- `funding_update` is emitted from changed WebSocket asset contexts and may cover many assets; filter by coin early.
 - Dust matters: if residual size falls below exchange precision or `minTradeUsd`, stop chasing it.
 - `ALO` / post-only orders can be rejected when they would cross; treat that as an execution branch, not a surprise.
 - Naked directional positions usually need explicit TP/SL or equivalent risk logic. Hedged multi-leg strategies need strategy-specific exits instead of cargo-cult TP/SL rules.

package/dist/auto/cli.js

@@ -29,7 +29,7 @@ Options (for run):
   --dry              Intercept write methods (no real trades)
   --verbose          Show debug output
   --id <name>        Custom automation ID (default: filename)
-  --poll <ms>        Poll interval in milliseconds (default: 10000)
+  --poll <ms>        REST fallback interval (default: 30000 with WS, 10000 with --no-ws)
   --no-ws            Disable WebSocket; fall back to REST-only polling
   --allow-sleep      Do not request OS idle-sleep inhibition for this run
 

package/dist/auto/examples/price-alert.js

@@ -74,7 +74,7 @@ export default function priceAlert(api) {
         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
+    // Periodic summary via the independent runtime scheduler
     api.on('tick', ({ pollCount }) => {
         if (pollCount % 10 === 0 && alertCount > 0) {
             api.log.info(`Summary: ${alertCount} alerts fired, last price: $${lastAlertPrice.toFixed(2)}`);

package/dist/auto/realtime.d.ts

@@ -0,0 +1,45 @@
+import type { AssetCtx, ClearinghouseState, OpenOrder } from '../core/types.js';
+import type { HyperliquidClient, RealtimeBookSnapshot, RealtimeDataProvider } from '../core/client.js';
+import { WebSocketManager, type WsEventMap } from '../core/ws.js';
+/**
+ * Runtime-owned WebSocket cache used transparently by HyperliquidClient read
+ * methods. While the socket is healthy, automation code calling getAllMids,
+ * getUserState(All), getSpotBalances, getMetaAndAssetCtxs, or getL2Book reads
+ * this cache. Missing/stale data returns null so the client falls back to REST.
+ */
+export declare class AutomationRealtimeData implements RealtimeDataProvider {
+    private readonly ws;
+    private readonly client;
+    private readonly user;
+    private readonly unified;
+    private readonly expectedOrderDexes;
+    private mids;
+    private assetCtxs;
+    private clearinghouse;
+    private spot;
+    private books;
+    private openOrders;
+    private bookSubscriptions;
+    private bookWaiters;
+    constructor(ws: WebSocketManager, client: HyperliquidClient, user: string, unified: boolean | null, expectedOrderDexes?: string[]);
+    get connected(): boolean;
+    getAllMids(): Record<string, string> | null;
+    getMainAssetCtxs(): AssetCtx[] | null;
+    getAllDexsAssetCtxs(): WsEventMap['allDexsAssetCtxs']['ctxs'] | null;
+    getUserState(user: string, dex?: string): ClearinghouseState | null;
+    getUserStateAll(user: string): ClearinghouseState | null;
+    getSpotBalances(user: string): ReturnType<RealtimeDataProvider['getSpotBalances']>;
+    getOpenOrders(user: string): OpenOrder[] | null;
+    getL2Book(coin: string): Promise<RealtimeBookSnapshot | null>;
+    /** Wait briefly for initial subscription snapshots before the first strategy hook runs. */
+    waitUntilReady(timeoutMs?: number): Promise<boolean>;
+    readinessSummary(): {
+        expectedOrderDexes: number;
+        seededOrderDexes: number;
+        missingOrderDexes: string[];
+    };
+    private coreFeedsReady;
+    private sameUser;
+    private fresh;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/auto/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../scripts/auto/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAWlE;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IAW/D,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAdrC,OAAO,CAAC,IAAI,CAA8C;IAC1D,OAAO,CAAC,SAAS,CAA8D;IAC/E,OAAO,CAAC,aAAa,CAAsF;IAC3G,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,KAAK,CAAkD;IAC/D,OAAO,CAAC,UAAU,CAAyC;IAC3D,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,WAAW,CAAsC;gBAGtC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,kBAAkB,GAAE,MAAM,EAAS;IAqBtD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAI3C,gBAAgB,IAAI,QAAQ,EAAE,GAAG,IAAI;IAOrC,mBAAmB,IAAI,UAAU,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI;IAIpE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAmBnE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IASxD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAUlF,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,IAAI;IAWzC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAiCnE,2FAA2F;IACrF,cAAc,CAAC,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1D,gBAAgB,IAAI;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;KAAE;IASzG,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,KAAK;CAId"}

package/dist/auto/realtime.js

@@ -0,0 +1,177 @@
+const MARKET_DATA_STALE_MS = 45_000;
+const BOOK_STALE_MS = 10_000;
+const BOOK_SEED_TIMEOUT_MS = 1_500;
+/**
+ * Runtime-owned WebSocket cache used transparently by HyperliquidClient read
+ * methods. While the socket is healthy, automation code calling getAllMids,
+ * getUserState(All), getSpotBalances, getMetaAndAssetCtxs, or getL2Book reads
+ * this cache. Missing/stale data returns null so the client falls back to REST.
+ */
+export class AutomationRealtimeData {
+    ws;
+    client;
+    user;
+    unified;
+    expectedOrderDexes;
+    mids = null;
+    assetCtxs = null;
+    clearinghouse = null;
+    spot = null;
+    books = new Map();
+    openOrders = new Map();
+    bookSubscriptions = new Set();
+    bookWaiters = new Map();
+    constructor(ws, client, user, unified, expectedOrderDexes = ['']) {
+        this.ws = ws;
+        this.client = client;
+        this.user = user;
+        this.unified = unified;
+        this.expectedOrderDexes = expectedOrderDexes;
+        ws.on('allMids', (data) => { this.mids = { value: data.mids, timestamp: Date.now() }; });
+        ws.on('allDexsAssetCtxs', (data) => { this.assetCtxs = { value: data.ctxs, timestamp: Date.now() }; });
+        ws.on('allDexsClearinghouseState', (data) => {
+            this.clearinghouse = { value: data.clearinghouseStates, timestamp: Date.now() };
+        });
+        ws.on('spotState', (data) => { this.spot = { value: data, timestamp: Date.now() }; });
+        ws.on('openOrders', (data) => {
+            if (this.sameUser(data.user))
+                this.openOrders.set(data.dex || '', { value: data.orders, timestamp: Date.now() });
+        });
+        ws.on('l2Book', (data) => {
+            this.books.set(data.coin, { value: data, timestamp: Date.now() });
+            const waiters = this.bookWaiters.get(data.coin);
+            if (waiters) {
+                for (const resolve of waiters)
+                    resolve();
+                waiters.clear();
+            }
+        });
+    }
+    get connected() {
+        return this.ws.connected;
+    }
+    getAllMids() {
+        return this.fresh(this.mids, MARKET_DATA_STALE_MS)?.value ?? null;
+    }
+    getMainAssetCtxs() {
+        const groups = this.fresh(this.assetCtxs, MARKET_DATA_STALE_MS)?.value;
+        if (!groups)
+            return null;
+        const main = groups.find(([dex]) => !dex || dex === 'main') ?? groups[0];
+        return main?.[1] ?? null;
+    }
+    getAllDexsAssetCtxs() {
+        return this.fresh(this.assetCtxs, MARKET_DATA_STALE_MS)?.value ?? null;
+    }
+    getUserState(user, dex) {
+        if (!this.sameUser(user))
+            return null;
+        const groups = this.clearinghouse?.value;
+        if (!groups)
+            return null;
+        const targetDex = dex ?? '';
+        const raw = groups.find(([name]) => (name || '') === targetDex)?.[1];
+        if (!raw)
+            return null;
+        const withdrawable = raw.withdrawable;
+        return {
+            ...raw,
+            marginSummary: raw.marginSummary && withdrawable != null
+                ? { ...raw.marginSummary, withdrawable }
+                : raw.marginSummary,
+            crossMarginSummary: raw.crossMarginSummary && withdrawable != null
+                ? { ...raw.crossMarginSummary, withdrawable }
+                : raw.crossMarginSummary,
+        };
+    }
+    getUserStateAll(user) {
+        if (!this.sameUser(user) || !this.clearinghouse || this.unified === null)
+            return null;
+        return this.client.userStateAllFromWs(this.clearinghouse.value, this.unified, this.spot ? { balances: this.spot.value.balances } : undefined);
+    }
+    getSpotBalances(user) {
+        if (!this.sameUser(user) || !this.spot)
+            return null;
+        return {
+            balances: this.spot.value.balances.map((balance) => ({
+                ...balance,
+                entryNtl: balance.entryNtl ?? '0',
+            })),
+        };
+    }
+    getOpenOrders(user) {
+        if (!this.sameUser(user) || !this.connected)
+            return null;
+        const orders = [];
+        for (const dex of new Set(['', ...this.expectedOrderDexes])) {
+            const entry = this.openOrders.get(dex);
+            if (!entry)
+                return null;
+            orders.push(...entry.value);
+        }
+        return orders;
+    }
+    async getL2Book(coin) {
+        const cached = this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS);
+        if (cached)
+            return cached.value;
+        if (!this.connected)
+            return null;
+        if (!this.bookSubscriptions.has(coin)) {
+            this.bookSubscriptions.add(coin);
+            try {
+                await this.ws.subscribeL2Book(coin);
+            }
+            catch {
+                this.bookSubscriptions.delete(coin);
+                return null;
+            }
+        }
+        const seeded = this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS);
+        if (seeded)
+            return seeded.value;
+        await new Promise((resolve) => {
+            const waiters = this.bookWaiters.get(coin) ?? new Set();
+            this.bookWaiters.set(coin, waiters);
+            const done = () => {
+                clearTimeout(timer);
+                waiters.delete(done);
+                resolve();
+            };
+            const timer = setTimeout(done, BOOK_SEED_TIMEOUT_MS);
+            waiters.add(done);
+        });
+        return this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS)?.value ?? null;
+    }
+    /** Wait briefly for initial subscription snapshots before the first strategy hook runs. */
+    async waitUntilReady(timeoutMs = 10_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (this.coreFeedsReady())
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        return this.coreFeedsReady();
+    }
+    readinessSummary() {
+        const expected = [...new Set(['', ...this.expectedOrderDexes])];
+        return {
+            expectedOrderDexes: expected.length,
+            seededOrderDexes: expected.filter((dex) => this.openOrders.has(dex)).length,
+            missingOrderDexes: expected.filter((dex) => !this.openOrders.has(dex)),
+        };
+    }
+    coreFeedsReady() {
+        const ordersReady = [...new Set(['', ...this.expectedOrderDexes])]
+            .every((dex) => this.openOrders.has(dex));
+        return Boolean(this.mids && this.assetCtxs && this.clearinghouse && this.spot && ordersReady);
+    }
+    sameUser(user) {
+        return user.toLowerCase() === this.user.toLowerCase();
+    }
+    fresh(entry, maxAgeMs) {
+        if (!this.connected || !entry || Date.now() - entry.timestamp > maxAgeMs)
+            return null;
+        return entry;
+    }
+}

package/dist/auto/realtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=realtime.test.d.ts.map

package/dist/auto/realtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.test.d.ts","sourceRoot":"","sources":["../../scripts/auto/realtime.test.ts"],"names":[],"mappings":""}

package/dist/auto/realtime.test.js

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { AutomationRealtimeData } from './realtime.js';
+class FakeWebSocket {
+    connected = true;
+    handlers = new Map();
+    on(event, handler) {
+        const set = this.handlers.get(event) ?? new Set();
+        set.add(handler);
+        this.handlers.set(event, set);
+    }
+    emit(event, value) {
+        for (const handler of this.handlers.get(event) ?? [])
+            handler(value);
+    }
+    async subscribeL2Book(coin) {
+        queueMicrotask(() => this.emit('l2Book', {
+            coin,
+            time: Date.now(),
+            levels: [
+                [{ px: '99', sz: '2', n: 1 }],
+                [{ px: '101', sz: '3', n: 1 }],
+            ],
+        }));
+        return {};
+    }
+}
+const ADDRESS = '0x0000000000000000000000000000000000000001';
+test('realtime cache serves subscribed market/account data and seeds books on demand', async () => {
+    const ws = new FakeWebSocket();
+    const mergedState = {
+        assetPositions: [],
+        marginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+        crossMarginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+        crossMaintenanceMarginUsed: '0',
+    };
+    const client = {
+        userStateAllFromWs: () => mergedState,
+    };
+    const cache = new AutomationRealtimeData(ws, client, ADDRESS, true);
+    ws.emit('allMids', { mids: { HYPE: '100' } });
+    ws.emit('allDexsAssetCtxs', { ctxs: [['', [{ funding: '0.0001', openInterest: '1', dayNtlVlm: '2', premium: '0', oraclePx: '100', markPx: '100', prevDayPx: '99' }]]] });
+    ws.emit('spotState', { balances: [{ coin: 'USDC', token: 0, total: '100', hold: '0' }] });
+    ws.emit('openOrders', { user: ADDRESS, dex: '', orders: [] });
+    ws.emit('allDexsClearinghouseState', {
+        user: ADDRESS,
+        clearinghouseStates: [['', {
+                    assetPositions: [],
+                    marginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+                    crossMarginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+                    crossMaintenanceMarginUsed: '0',
+                    withdrawable: '100',
+                }]],
+    });
+    assert.equal(await cache.waitUntilReady(20), true);
+    assert.equal(cache.getAllMids()?.HYPE, '100');
+    assert.equal(cache.getMainAssetCtxs()?.[0]?.funding, '0.0001');
+    assert.equal(cache.getSpotBalances(ADDRESS)?.balances[0]?.entryNtl, '0');
+    assert.deepEqual(cache.getOpenOrders(ADDRESS), []);
+    assert.equal(cache.getUserState(ADDRESS)?.marginSummary.accountValue, '100');
+    assert.equal(cache.getUserStateAll(ADDRESS)?.marginSummary.accountValue, '100');
+    const book = await cache.getL2Book('HYPE');
+    assert.equal(book?.levels[0][0]?.px, '99');
+    assert.equal(book?.levels[1][0]?.px, '101');
+});
+test('realtime cache declines reads while disconnected so the client can fall back to REST', () => {
+    const ws = new FakeWebSocket();
+    const client = { userStateAllFromWs: () => null };
+    const cache = new AutomationRealtimeData(ws, client, ADDRESS, false);
+    ws.emit('allMids', { mids: { HYPE: '100' } });
+    ws.connected = false;
+    assert.equal(cache.getAllMids(), null);
+});

package/dist/auto/runtime.d.ts

@@ -13,9 +13,9 @@ export interface RuntimeOptions {
     /** 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.
+     * Enable WebSocket-first market/account data and events. REST is used for
+     * initial static metadata, minute reconciliation, and automatic fallback
+     * while the socket is unavailable.
      * @default true
      */
     useWebSocket?: boolean;

package/dist/auto/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../scripts/auto/runtime.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA4C,wBAAwB,IAAI,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG5H,OAAO,KAAK,EAYV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAqYpB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAKD,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAE3D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEvE;AAED,8EAA8E;AAC9E,OAAO,EAAE,qBAAqB,IAAI,wBAAwB,EAAE,CAAC;AAE7D,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAijBzF"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../scripts/auto/runtime.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA4C,wBAAwB,IAAI,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG5H,OAAO,KAAK,EAYV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAqYpB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAKD,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAE3D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEvE;AAED,8EAA8E;AAC9E,OAAO,EAAE,qBAAqB,IAAI,wBAAwB,EAAE,CAAC;AAE7D,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+nBzF"}