openbroker 1.9.1 → 1.9.3

package/scripts/auto/examples/dca.ts

@@ -1,6 +1,6 @@
 // DCA (Dollar Cost Averaging) — Buy fixed USD amounts at regular intervals
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Dollar cost averaging — buy fixed USD amounts at regular intervals',
@@ -12,6 +12,25 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  const amount = Number(values.amount ?? 100);
+  const count = Number(values.count ?? 24);
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: amount * 1.1,
+    maxPositionUsd: amount * count * 1.1,
+    maxTotalExposureUsd: amount * count * 1.1,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 5,
+    maxOrdersPerMinute: 5,
+    maxSlippageBps: 50,
+    allowMarketOrders: true,
+    allowAccountWideCancel: false,
+  };
+}
+
 export default function dca(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'HYPE')!;
   const AMOUNT_USD = api.state.get<number>('amount', 100)!;
@@ -43,7 +62,7 @@ export default function dca(api: AutomationAPI) {
     const size = AMOUNT_USD / price;
     api.log.info(`[${purchased + 1}/${MAX_PURCHASES}] Buying ~$${AMOUNT_USD} of ${COIN} @ $${price.toFixed(2)}`);
 
-    const response = await api.client.marketOrder(COIN, true, size);
+    const response = await api.client.marketOrder(COIN, true, size, undefined, 1);
     if (response.status === 'ok' && response.response && typeof response.response === 'object') {
       const status = response.response.data.statuses[0];
       if (status?.filled) {

package/scripts/auto/examples/funding-arb.ts

@@ -1,6 +1,6 @@
 // Funding Arbitrage — Collect funding by positioning opposite to the crowd
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Funding arbitrage — collect funding by positioning opposite to the crowd',
@@ -13,6 +13,24 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  const sizeUsd = Number(values.sizeUsd ?? 5000);
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: sizeUsd * 1.1,
+    maxPositionUsd: sizeUsd * 1.1,
+    maxTotalExposureUsd: sizeUsd * 1.1,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 5,
+    maxOrdersPerMinute: 4,
+    maxSlippageBps: 50,
+    allowMarketOrders: true,
+    allowAccountWideCancel: false,
+  };
+}
+
 export default function fundingArb(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'HYPE')!;
   const SIZE_USD = api.state.get<number>('sizeUsd', 5000)!;
@@ -48,7 +66,7 @@ export default function fundingArb(api: AutomationAPI) {
       if (shouldClose) {
         api.log.info(`Funding dropped to ${annualizedPct.toFixed(2)}% (below ${CLOSE_AT}%), closing ${positionSide}`);
         const closeIsBuy = positionSide === 'short';
-        await api.client.marketOrder(coin, closeIsBuy, positionSize);
+        await api.client.marketOrder(coin, closeIsBuy, positionSize, undefined, 1);
 
         inPosition = false;
         api.state.set('inPosition', false);
@@ -69,7 +87,7 @@ export default function fundingArb(api: AutomationAPI) {
       const size = SIZE_USD / price;
 
       api.log.info(`Funding at ${annualizedPct.toFixed(2)}% — opening ${side} ${size.toFixed(6)} ${coin}`);
-      const response = await api.client.marketOrder(coin, !shouldShort, size);
+      const response = await api.client.marketOrder(coin, !shouldShort, size, undefined, 1);
 
       if (response.status === 'ok' && response.response && typeof response.response === 'object') {
         const status = response.response.data.statuses[0];

package/scripts/auto/examples/grid.ts

@@ -1,6 +1,6 @@
 // Grid Trading — Place buy/sell orders at evenly spaced price levels
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Grid trading — buy/sell orders at evenly spaced price levels',
@@ -14,6 +14,23 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: 10_000,
+    maxPositionUsd: 25_000,
+    maxTotalExposureUsd: 25_000,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 25,
+    maxOrdersPerMinute: 25,
+    maxSlippageBps: 50,
+    allowMarketOrders: false,
+    allowAccountWideCancel: false,
+  };
+}
+
 interface GridLevel {
   price: number;
   side: 'buy' | 'sell';
@@ -58,7 +75,7 @@ export default function grid(api: AutomationAPI) {
 
       const level: GridLevel = { price, side, size: SIZE };
 
-      const response = await api.client.limitOrder(COIN, side === 'buy', SIZE, price, 'Gtc', false);
+      const response = await api.client.limitOrder(COIN, side === 'buy', SIZE, price, 'Gtc', false, 1);
       if (response.status === 'ok' && response.response && typeof response.response === 'object') {
         const status = response.response.data.statuses[0];
         if (status?.resting) {
@@ -105,7 +122,7 @@ export default function grid(api: AutomationAPI) {
 
       if (oppositePrice < lower || oppositePrice > upper) continue;
 
-      const response = await api.client.limitOrder(COIN, oppositeSide === 'buy', SIZE, oppositePrice, 'Gtc', false);
+      const response = await api.client.limitOrder(COIN, oppositeSide === 'buy', SIZE, oppositePrice, 'Gtc', false, 1);
       if (response.status === 'ok' && response.response && typeof response.response === 'object') {
         const status = response.response.data.statuses[0];
         if (status?.resting) {

package/scripts/auto/examples/mm-maker.ts

@@ -1,6 +1,6 @@
 // Maker-Only Market Making — ALO orders that guarantee maker rebates
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Maker-only market making — ALO orders for guaranteed maker rebates',
@@ -13,6 +13,23 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: 10_000,
+    maxPositionUsd: 25_000,
+    maxTotalExposureUsd: 25_000,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 10,
+    maxOrdersPerMinute: 60,
+    maxSlippageBps: 25,
+    allowMarketOrders: false,
+    allowAccountWideCancel: false,
+  };
+}
+
 export default function mmMaker(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'HYPE')!;
   const SIZE = api.state.get<number>('size', 0.1)!;
@@ -95,7 +112,7 @@ export default function mmMaker(api: AutomationAPI) {
 
     // Place ALO bid
     if (shouldBid && !bidOid && safeBid < book.bestAsk) {
-      const resp = await api.client.limitOrder(COIN, true, SIZE, safeBid, 'Alo', false);
+      const resp = await api.client.limitOrder(COIN, true, SIZE, safeBid, 'Alo', false, 1);
       if (resp.status === 'ok' && resp.response && typeof resp.response === 'object') {
         const s = resp.response.data.statuses[0];
         if (s?.resting) { bidOid = s.resting.oid; bidPrice = safeBid; }
@@ -105,7 +122,7 @@ export default function mmMaker(api: AutomationAPI) {
 
     // Place ALO ask
     if (shouldAsk && !askOid && safeAsk > book.bestBid) {
-      const resp = await api.client.limitOrder(COIN, false, SIZE, safeAsk, 'Alo', false);
+      const resp = await api.client.limitOrder(COIN, false, SIZE, safeAsk, 'Alo', false, 1);
       if (resp.status === 'ok' && resp.response && typeof resp.response === 'object') {
         const s = resp.response.data.statuses[0];
         if (s?.resting) { askOid = s.resting.oid; askPrice = safeAsk; }

package/scripts/auto/examples/mm-spread.ts

@@ -1,6 +1,6 @@
 // Market Making (Spread) — Quote bid/ask around mid with inventory skewing
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Market making — quote bid/ask around mid price with inventory skewing',
@@ -13,6 +13,23 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: 10_000,
+    maxPositionUsd: 25_000,
+    maxTotalExposureUsd: 25_000,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 10,
+    maxOrdersPerMinute: 60,
+    maxSlippageBps: 25,
+    allowMarketOrders: false,
+    allowAccountWideCancel: false,
+  };
+}
+
 export default function mmSpread(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'HYPE')!;
   const SIZE = api.state.get<number>('size', 0.1)!;
@@ -91,14 +108,14 @@ export default function mmSpread(api: AutomationAPI) {
 
     // Place new quotes
     if (shouldBid && !bidOid) {
-      const resp = await api.client.limitOrder(COIN, true, SIZE, targetBid, 'Gtc', false);
+      const resp = await api.client.limitOrder(COIN, true, SIZE, targetBid, 'Gtc', false, 1);
       if (resp.status === 'ok' && resp.response && typeof resp.response === 'object') {
         const s = resp.response.data.statuses[0];
         if (s?.resting) { bidOid = s.resting.oid; bidPrice = targetBid; }
       }
     }
     if (shouldAsk && !askOid) {
-      const resp = await api.client.limitOrder(COIN, false, SIZE, targetAsk, 'Gtc', false);
+      const resp = await api.client.limitOrder(COIN, false, SIZE, targetAsk, 'Gtc', false, 1);
       if (resp.status === 'ok' && resp.response && typeof resp.response === 'object') {
         const s = resp.response.data.statuses[0];
         if (s?.resting) { askOid = s.resting.oid; askPrice = targetAsk; }

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

@@ -1,7 +1,7 @@
 // Price Alert — Real-time price monitoring via WebSocket
 // Showcases WebSocket-driven price_change and order_update events
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Real-time price alerts via WebSocket — log price moves and order updates',
@@ -13,6 +13,8 @@ export const config: AutomationConfig = {
   },
 };
 
+export const guardrails: AutomationGuardrails = { mode: 'read-only' };
+
 export default function priceAlert(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'BTC')!;
   const THRESHOLD = api.state.get<number>('threshold', 0.1)!;

package/scripts/auto/guardrails.test.ts

@@ -0,0 +1,227 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { HyperliquidClient } from '../core/client.js';
+import {
+  CLIENT_WRITE_METHODS,
+  GuardrailViolation,
+  createGuardrailedClient,
+  validateAutomationGuardrails,
+} from './guardrails.js';
+import { listExamples, loadAutomation } from './loader.js';
+import type { AutomationLogger, TradingAutomationGuardrails } from './types.js';
+
+const logger: AutomationLogger = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+};
+
+function tradingPolicy(overrides: Partial<TradingAutomationGuardrails> = {}): TradingAutomationGuardrails {
+  return {
+    mode: 'trading',
+    allowedMarkets: ['ETH'],
+    maxOrderUsd: 1_000,
+    maxPositionUsd: 2_000,
+    maxTotalExposureUsd: 5_000,
+    maxLeverage: 2,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 10,
+    maxOrdersPerMinute: 10,
+    maxSlippageBps: 40,
+    allowMarketOrders: true,
+    allowAccountWideCancel: false,
+    ...overrides,
+  };
+}
+
+function mockClient(options: {
+  positions?: Array<{ coin: string; size: number; price: number; leverage?: number }>;
+  spotBalances?: Array<{ coin: string; total: string }>;
+  spotData?: {
+    meta: {
+      tokens: Array<{ index: number; name: string }>;
+      universe: Array<{ name: string; tokens: [number, number] }>;
+    };
+    assetCtxs: Array<{ coin?: string; midPx: string; markPx: string }>;
+  };
+} = {}) {
+  const calls: Array<{ method: string; args: unknown[] }> = [];
+  const client = {
+    address: '0x0000000000000000000000000000000000000001',
+    walletAddress: '0x0000000000000000000000000000000000000002',
+    isApiWallet: true,
+    async getUserStateAll() {
+      return {
+        assetPositions: (options.positions ?? []).map((position) => ({
+          position: {
+            coin: position.coin,
+            szi: String(position.size),
+            positionValue: String(Math.abs(position.size * position.price)),
+            leverage: { type: 'cross', value: position.leverage ?? 1 },
+          },
+        })),
+        marginSummary: { accountValue: '10000', totalMarginUsed: '0' },
+      };
+    },
+    async getAllMids() { return { ETH: '2000', BTC: '50000' }; },
+    async getOpenOrders() { return []; },
+    async getSpotBalances() { return { balances: options.spotBalances ?? [] }; },
+    async getSpotMetaAndAssetCtxs() {
+      return options.spotData ?? { meta: { tokens: [], universe: [] }, assetCtxs: [] };
+    },
+    resolveOutcomeRef() {
+      return { outcome: 1, side: 0, encoding: 10, coin: '#10', tokenName: '+10', assetId: 100000010 };
+    },
+    async marketOrder(...args: unknown[]) {
+      calls.push({ method: 'marketOrder', args });
+      return { status: 'ok' };
+    },
+    async limitOrder(...args: unknown[]) {
+      calls.push({ method: 'limitOrder', args });
+      return { status: 'ok' };
+    },
+    async bulkOrder(...args: unknown[]) {
+      calls.push({ method: 'bulkOrder', args });
+      return { status: 'ok' };
+    },
+    async spotLimitOrder(...args: unknown[]) {
+      calls.push({ method: 'spotLimitOrder', args });
+      return { status: 'ok' };
+    },
+  } as unknown as HyperliquidClient;
+  return { client, calls };
+}
+
+test('guardrail schema rejects missing and internally inconsistent limits', () => {
+  assert.throws(
+    () => validateAutomationGuardrails({ mode: 'trading' }),
+    /allowedMarkets/,
+  );
+  assert.throws(
+    () => validateAutomationGuardrails(tradingPolicy({ maxOrderUsd: 3_000 })),
+    /maxOrderUsd.*maxPositionUsd/,
+  );
+  assert.deepEqual(validateAutomationGuardrails({ mode: 'read-only' }), { mode: 'read-only' });
+});
+
+test('all client write families are included in the enforcement boundary', () => {
+  for (const method of [
+    'bulkOrder', 'bulkCancel', 'scheduleCancel',
+    'outcomeOrder', 'outcomeMarketOrder', 'outcomeLimitOrder',
+  ]) {
+    assert.equal(CLIENT_WRITE_METHODS.has(method), true, `${method} must be guarded`);
+  }
+});
+
+test('every bundled example exports a valid guardrail policy', async () => {
+  for (const example of listExamples()) {
+    const loaded = await loadAutomation(example.path, { config: {} });
+    assert.ok(loaded.guardrails.mode === 'read-only' || loaded.guardrails.mode === 'trading');
+  }
+});
+
+test('read-only policy blocks every write before it reaches the client', async () => {
+  const { client, calls } = mockClient();
+  const guarded = createGuardrailedClient(client, {
+    policy: { mode: 'read-only' },
+    rawClient: client,
+    log: logger,
+  });
+
+  await assert.rejects(
+    guarded.bulkOrder([{ coin: 'ETH', isBuy: true, size: 0.1, price: 2000 }]),
+    (error: unknown) => error instanceof GuardrailViolation && error.code === 'read-only',
+  );
+  assert.equal(calls.length, 0);
+});
+
+test('trading policy blocks disallowed markets, missing leverage, and oversized orders', async () => {
+  const { client, calls } = mockClient();
+  const guarded = createGuardrailedClient(client, {
+    policy: tradingPolicy(),
+    rawClient: client,
+    log: logger,
+  });
+
+  await assert.rejects(
+    guarded.limitOrder('BTC', true, 0.01, 50_000, 'Gtc', false, 1),
+    (error: unknown) => error instanceof GuardrailViolation && error.code === 'market-not-allowed',
+  );
+  await assert.rejects(
+    guarded.limitOrder('ETH', true, 0.1, 2_000),
+    (error: unknown) => error instanceof GuardrailViolation && error.code === 'leverage-required',
+  );
+  await assert.rejects(
+    guarded.limitOrder('ETH', true, 0.6, 2_000, 'Gtc', false, 1),
+    (error: unknown) => error instanceof GuardrailViolation && error.code === 'order-notional',
+  );
+  assert.equal(calls.length, 0);
+});
+
+test('valid market orders execute with runtime-capped slippage', async () => {
+  const { client, calls } = mockClient();
+  const guarded = createGuardrailedClient(client, {
+    policy: tradingPolicy(),
+    rawClient: client,
+    log: logger,
+  });
+
+  await guarded.marketOrder('ETH', true, 0.1, undefined, 1);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0], {
+    method: 'marketOrder',
+    args: ['ETH', true, 0.1, 40, 1],
+  });
+});
+
+test('account-wide exposure is checked while genuine reductions remain available above caps', async () => {
+  const exposed = mockClient({ positions: [{ coin: 'BTC', size: 0.1, price: 50_000 }] });
+  const exposureGuarded = createGuardrailedClient(exposed.client, {
+    policy: tradingPolicy({ maxTotalExposureUsd: 5_100 }),
+    rawClient: exposed.client,
+    log: logger,
+  });
+  await assert.rejects(
+    exposureGuarded.limitOrder('ETH', true, 0.1, 2_000, 'Gtc', false, 1),
+    (error: unknown) => error instanceof GuardrailViolation && error.code === 'total-exposure',
+  );
+
+  const reducing = mockClient({ positions: [{ coin: 'ETH', size: 1, price: 2_000 }] });
+  const reductionGuarded = createGuardrailedClient(reducing.client, {
+    policy: tradingPolicy({ maxPositionUsd: 1_000, maxTotalExposureUsd: 1_000 }),
+    rawClient: reducing.client,
+    log: logger,
+  });
+  await reductionGuarded.marketOrder('ETH', false, 0.1);
+  assert.equal(reducing.calls.length, 1);
+});
+
+test('spot exposure joins market contexts by pair identifier instead of array position', async () => {
+  const { client, calls } = mockClient({
+    spotBalances: [{ coin: 'HYPE', total: '3' }],
+    spotData: {
+      meta: {
+        tokens: [{ index: 0, name: 'USDC' }, { index: 1, name: 'HYPE' }],
+        universe: [{ name: '@107', tokens: [1, 0] }],
+      },
+      assetCtxs: [
+        { coin: '@999', midPx: '99999', markPx: '99999' },
+        { coin: '@107', midPx: '62.5', markPx: '62.5' },
+      ],
+    },
+  });
+  const guarded = createGuardrailedClient(client, {
+    policy: tradingPolicy({
+      allowedMarkets: ['spot:HYPE'],
+      maxOrderUsd: 100,
+      maxPositionUsd: 500,
+      maxTotalExposureUsd: 500,
+    }),
+    rawClient: client,
+    log: logger,
+  });
+
+  await guarded.spotLimitOrder('HYPE', true, 0.1, 62.5, 'Gtc');
+  assert.equal(calls.length, 1);
+});