openbroker 1.0.66 → 1.0.68

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

@@ -0,0 +1,98 @@
+// Funding Arbitrage — Collect funding by positioning opposite to the crowd
+
+import type { AutomationAPI, AutomationConfig } from '../types.js';
+
+export const config: AutomationConfig = {
+  description: 'Funding arbitrage — collect funding by positioning opposite to the crowd',
+  fields: {
+    coin:       { type: 'string', description: 'Asset to trade', default: 'HYPE' },
+    sizeUsd:    { type: 'number', description: 'Position size in USD notional', default: 5000 },
+    minFunding: { type: 'number', description: 'Min annualized % to enter', default: 20 },
+    maxFunding: { type: 'number', description: 'Max annualized % — avoid squeezes', default: 200 },
+    closeAt:    { type: 'number', description: 'Close when funding drops below this %', default: 5 },
+  },
+};
+
+export default function fundingArb(api: AutomationAPI) {
+  const COIN = api.state.get<string>('coin', 'HYPE')!;
+  const SIZE_USD = api.state.get<number>('sizeUsd', 5000)!;
+  const MIN_FUNDING = api.state.get<number>('minFunding', 20)!;
+  const MAX_FUNDING = api.state.get<number>('maxFunding', 200)!;
+  const CLOSE_AT = api.state.get<number>('closeAt', 5)!;
+
+  let inPosition = api.state.get<boolean>('inPosition', false)!;
+  let positionSide = api.state.get<string>('positionSide', '')!;
+  let entryPrice = api.state.get<number>('entryPrice', 0)!;
+  let positionSize = api.state.get<number>('positionSize', 0)!;
+  let totalFunding = api.state.get<number>('totalFunding', 0)!;
+
+  api.onStart(() => {
+    api.log.info(`Funding arb: ${COIN} | $${SIZE_USD} | Enter >${MIN_FUNDING}% | Close <${CLOSE_AT}%`);
+    if (inPosition) {
+      api.log.info(`Resuming ${positionSide} position: ${positionSize.toFixed(6)} @ $${entryPrice.toFixed(2)}`);
+    }
+  });
+
+  api.on('funding_update', async ({ coin, annualized }) => {
+    if (coin !== COIN) return;
+
+    const annualizedPct = annualized * 100;
+    const absAnnualized = Math.abs(annualizedPct);
+
+    if (inPosition) {
+      // Check if we should close
+      const shouldClose =
+        (positionSide === 'short' && annualizedPct < CLOSE_AT) ||
+        (positionSide === 'long' && annualizedPct > -CLOSE_AT);
+
+      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);
+
+        inPosition = false;
+        api.state.set('inPosition', false);
+        api.log.info(`Position closed. Funding collected: ~$${totalFunding.toFixed(2)}`);
+      } else {
+        api.log.debug(`${coin} funding: ${annualizedPct.toFixed(2)}% — holding ${positionSide}`);
+      }
+      return;
+    }
+
+    // Not in position — check if we should enter
+    if (absAnnualized >= MIN_FUNDING && absAnnualized <= MAX_FUNDING) {
+      const shouldShort = annualizedPct > 0; // Positive = longs pay shorts
+      const side = shouldShort ? 'short' : 'long';
+
+      const mids = await api.client.getAllMids();
+      const price = parseFloat(mids[coin]);
+      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);
+
+      if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+        const status = response.response.data.statuses[0];
+        if (status?.filled) {
+          positionSize = parseFloat(status.filled.totalSz);
+          entryPrice = parseFloat(status.filled.avgPx);
+          positionSide = side;
+          inPosition = true;
+
+          api.state.set('inPosition', true);
+          api.state.set('positionSide', side);
+          api.state.set('entryPrice', entryPrice);
+          api.state.set('positionSize', positionSize);
+
+          api.log.info(`Entered ${side} ${positionSize.toFixed(6)} @ $${entryPrice.toFixed(2)}`);
+        }
+      }
+    }
+  });
+
+  api.onStop(() => {
+    if (inPosition) {
+      api.log.warn(`Stopping with open ${positionSide} position of ${positionSize.toFixed(6)} ${COIN} — close manually if desired`);
+    }
+  });
+}

package/scripts/auto/examples/grid.ts

@@ -0,0 +1,135 @@
+// Grid Trading — Place buy/sell orders at evenly spaced price levels
+
+import type { AutomationAPI, AutomationConfig } from '../types.js';
+
+export const config: AutomationConfig = {
+  description: 'Grid trading — buy/sell orders at evenly spaced price levels',
+  fields: {
+    coin:  { type: 'string', description: 'Asset to trade', default: 'HYPE' },
+    lower: { type: 'number', description: 'Lower price bound (default: auto -5% from mid)', default: 0 },
+    upper: { type: 'number', description: 'Upper price bound (default: auto +5% from mid)', default: 0 },
+    grids: { type: 'number', description: 'Number of grid levels', default: 10 },
+    size:  { type: 'number', description: 'Size per level in base asset', default: 0.1 },
+    mode:  { type: 'string', description: 'Grid mode: neutral, long, or short', default: 'neutral' },
+  },
+};
+
+interface GridLevel {
+  price: number;
+  side: 'buy' | 'sell';
+  size: number;
+  oid?: number;
+}
+
+export default function grid(api: AutomationAPI) {
+  const COIN = api.state.get<string>('coin', 'HYPE')!;
+  const GRIDS = api.state.get<number>('grids', 10)!;
+  const SIZE = api.state.get<number>('size', 0.1)!;
+  const MODE = api.state.get<string>('mode', 'neutral')!;
+
+  let levels: GridLevel[] = [];
+  let realizedPnl = api.state.get<number>('realizedPnl', 0)!;
+  let initialized = false;
+
+  api.onStart(async () => {
+    const mids = await api.client.getAllMids();
+    const mid = parseFloat(mids[COIN]);
+    if (!mid) {
+      api.log.error(`No price for ${COIN}`);
+      return;
+    }
+
+    const lower = api.state.get<number>('lower', mid * 0.95)!;
+    const upper = api.state.get<number>('upper', mid * 1.05)!;
+    const spacing = (upper - lower) / (GRIDS - 1);
+
+    api.log.info(`Grid: ${COIN} ${api.utils.formatUsd(lower)}-${api.utils.formatUsd(upper)} | ${GRIDS} levels | ${SIZE}/level | ${MODE}`);
+
+    // Build and place grid
+    for (let i = 0; i < GRIDS; i++) {
+      const price = lower + spacing * i;
+      let side: 'buy' | 'sell';
+      if (MODE === 'long') side = 'buy';
+      else if (MODE === 'short') side = 'sell';
+      else side = price < mid ? 'buy' : 'sell';
+
+      // Skip levels too close to mid
+      if (Math.abs(price - mid) / mid < 0.001) continue;
+
+      const level: GridLevel = { price, side, size: SIZE };
+
+      const response = await api.client.limitOrder(COIN, side === 'buy', SIZE, price, 'Gtc', false);
+      if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+        const status = response.response.data.statuses[0];
+        if (status?.resting) {
+          level.oid = status.resting.oid;
+          api.log.info(`${side.toUpperCase()} @ ${api.utils.formatUsd(price)} — OID: ${level.oid}`);
+        } else if (status?.filled) {
+          api.log.info(`${side.toUpperCase()} @ ${api.utils.formatUsd(price)} — filled immediately`);
+        }
+      }
+
+      levels.push(level);
+      await api.utils.sleep(100);
+    }
+
+    initialized = true;
+    api.log.info(`Grid initialized: ${levels.filter(l => l.oid).length} open orders`);
+  });
+
+  // Monitor fills and replace with opposite orders
+  api.on('tick', async () => {
+    if (!initialized || levels.length === 0) return;
+
+    const openOrders = await api.client.getOpenOrders();
+    const openOids = new Set(openOrders.filter(o => o.coin === COIN).map(o => o.oid));
+
+    const mids = await api.client.getAllMids();
+    const mid = parseFloat(mids[COIN]);
+    const lower = api.state.get<number>('lower', mid * 0.95)!;
+    const upper = api.state.get<number>('upper', mid * 1.05)!;
+    const spacing = (upper - lower) / (GRIDS - 1);
+
+    for (const level of levels) {
+      if (!level.oid || openOids.has(level.oid)) continue;
+
+      // Order was filled
+      api.log.info(`${level.side.toUpperCase()} FILLED @ ${api.utils.formatUsd(level.price)}`);
+      level.oid = undefined;
+
+      if (MODE !== 'neutral') continue;
+
+      // Place opposite order
+      const oppositeSide = level.side === 'buy' ? 'sell' : 'buy';
+      const oppositePrice = level.side === 'buy' ? level.price + spacing : level.price - spacing;
+
+      if (oppositePrice < lower || oppositePrice > upper) continue;
+
+      const response = await api.client.limitOrder(COIN, oppositeSide === 'buy', SIZE, oppositePrice, 'Gtc', false);
+      if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+        const status = response.response.data.statuses[0];
+        if (status?.resting) {
+          const newLevel: GridLevel = { price: oppositePrice, side: oppositeSide, size: SIZE, oid: status.resting.oid };
+          levels.push(newLevel);
+
+          if (level.side === 'buy') {
+            realizedPnl += (oppositePrice - level.price) * SIZE;
+          }
+
+          api.state.set('realizedPnl', realizedPnl);
+          api.log.info(`Placed ${oppositeSide.toUpperCase()} @ ${api.utils.formatUsd(oppositePrice)} | PnL: ${api.utils.formatUsd(realizedPnl)}`);
+        }
+      }
+    }
+  });
+
+  api.onStop(async () => {
+    api.log.info('Cancelling grid orders...');
+    for (const level of levels) {
+      if (level.oid) {
+        try { await api.client.cancel(COIN, level.oid); } catch { /* may be filled */ }
+      }
+    }
+    api.log.info(`Grid stopped. Realized PnL: ${api.utils.formatUsd(realizedPnl)}`);
+  });
+}

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

@@ -0,0 +1,125 @@
+// Maker-Only Market Making — ALO orders that guarantee maker rebates
+
+import type { AutomationAPI, AutomationConfig } from '../types.js';
+
+export const config: AutomationConfig = {
+  description: 'Maker-only market making — ALO orders for guaranteed maker rebates',
+  fields: {
+    coin:        { type: 'string', description: 'Asset to market make', default: 'HYPE' },
+    size:        { type: 'number', description: 'Order size on each side (base asset)', default: 0.1 },
+    offsetBps:   { type: 'number', description: 'Offset from best bid/ask in bps', default: 1 },
+    maxPosition: { type: 'number', description: 'Max net position (default: 3x size)', default: 0.3 },
+    skewFactor:  { type: 'number', description: 'Inventory skew aggressiveness', default: 2.0 },
+  },
+};
+
+export default function mmMaker(api: AutomationAPI) {
+  const COIN = api.state.get<string>('coin', 'HYPE')!;
+  const SIZE = api.state.get<number>('size', 0.1)!;
+  const OFFSET_BPS = api.state.get<number>('offsetBps', 1)!;
+  const MAX_POS = api.state.get<number>('maxPosition', SIZE * 3)!;
+  const SKEW = api.state.get<number>('skewFactor', 2.0)!;
+
+  let bidOid: number | undefined;
+  let askOid: number | undefined;
+  let bidPrice = 0;
+  let askPrice = 0;
+  let totalBought = 0;
+  let totalSold = 0;
+  let totalBuyCost = 0;
+  let totalSellRevenue = 0;
+  let rejections = 0;
+
+  const offsetFraction = OFFSET_BPS / 10000;
+
+  api.onStart(() => {
+    api.log.info(`Maker MM: ${COIN} | ${SIZE}/side | ${OFFSET_BPS}bps offset | ALO only`);
+  });
+
+  api.on('tick', async () => {
+    const book = await api.client.getL2Book(COIN);
+    if (book.bestBid === 0 || book.bestAsk === 0) return;
+
+    // Get position
+    const userState = await api.client.getUserState();
+    const pos = userState.assetPositions.find(p => p.position.coin === COIN);
+    const position = pos ? parseFloat(pos.position.szi) : 0;
+
+    // Check fills
+    const openOrders = await api.client.getOpenOrders();
+    const openOids = new Set(openOrders.filter(o => o.coin === COIN).map(o => o.oid));
+
+    if (bidOid && !openOids.has(bidOid)) {
+      totalBought += SIZE;
+      totalBuyCost += bidPrice * SIZE;
+      api.log.info(`BID FILLED @ ${api.utils.formatUsd(bidPrice)} | Pos: ${position.toFixed(4)} | +rebate`);
+      bidOid = undefined;
+    }
+    if (askOid && !openOids.has(askOid)) {
+      totalSold += SIZE;
+      totalSellRevenue += askPrice * SIZE;
+      api.log.info(`ASK FILLED @ ${api.utils.formatUsd(askPrice)} | Pos: ${position.toFixed(4)} | +rebate`);
+      askOid = undefined;
+    }
+
+    // Inventory skew
+    const ratio = Math.max(-1, Math.min(1, position / MAX_POS));
+    const bidSkewMult = 1 + ratio * SKEW;
+    const askSkewMult = 1 - ratio * SKEW;
+
+    const targetBid = book.bestBid * (1 - offsetFraction * Math.max(0.1, bidSkewMult));
+    const targetAsk = book.bestAsk * (1 + offsetFraction * Math.max(0.1, askSkewMult));
+
+    // Ensure no crossing
+    const safeBid = Math.min(targetBid, book.bestAsk * 0.9999);
+    const safeAsk = Math.max(targetAsk, book.bestBid * 1.0001);
+
+    const shouldBid = position < MAX_POS;
+    const shouldAsk = position > -MAX_POS;
+
+    // Cancel stale quotes
+    if (bidOid) {
+      const drift = Math.abs(bidPrice - safeBid) / book.midPrice;
+      if (drift > 0.0005 || !shouldBid) {
+        try { await api.client.cancel(COIN, bidOid); } catch { /* */ }
+        bidOid = undefined;
+      }
+    }
+    if (askOid) {
+      const drift = Math.abs(askPrice - safeAsk) / book.midPrice;
+      if (drift > 0.0005 || !shouldAsk) {
+        try { await api.client.cancel(COIN, askOid); } catch { /* */ }
+        askOid = undefined;
+      }
+    }
+
+    // Place ALO bid
+    if (shouldBid && !bidOid && safeBid < book.bestAsk) {
+      const resp = await api.client.limitOrder(COIN, true, SIZE, safeBid, 'Alo', false);
+      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; }
+        else if (s?.error) { rejections++; }
+      }
+    }
+
+    // Place ALO ask
+    if (shouldAsk && !askOid && safeAsk > book.bestBid) {
+      const resp = await api.client.limitOrder(COIN, false, SIZE, safeAsk, 'Alo', false);
+      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; }
+        else if (s?.error) { rejections++; }
+      }
+    }
+  });
+
+  api.onStop(async () => {
+    if (bidOid) try { await api.client.cancel(COIN, bidOid); } catch { /* */ }
+    if (askOid) try { await api.client.cancel(COIN, askOid); } catch { /* */ }
+    const pnl = totalSellRevenue - totalBuyCost;
+    const volume = totalBuyCost + totalSellRevenue;
+    const rebates = volume * 0.00003;
+    api.log.info(`Maker MM stopped. PnL: ${api.utils.formatUsd(pnl)} | Rebates: ~${api.utils.formatUsd(rebates)} | Rejections: ${rejections}`);
+  });
+}

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

@@ -0,0 +1,115 @@
+// Market Making (Spread) — Quote bid/ask around mid with inventory skewing
+
+import type { AutomationAPI, AutomationConfig } from '../types.js';
+
+export const config: AutomationConfig = {
+  description: 'Market making — quote bid/ask around mid price with inventory skewing',
+  fields: {
+    coin:        { type: 'string', description: 'Asset to market make', default: 'HYPE' },
+    size:        { type: 'number', description: 'Order size on each side (base asset)', default: 0.1 },
+    spreadBps:   { type: 'number', description: 'Spread in bps from mid price', default: 10 },
+    maxPosition: { type: 'number', description: 'Max net position before pausing side (default: 3x size)', default: 0.3 },
+    skewFactor:  { type: 'number', description: 'Inventory skew aggressiveness', default: 2.0 },
+  },
+};
+
+export default function mmSpread(api: AutomationAPI) {
+  const COIN = api.state.get<string>('coin', 'HYPE')!;
+  const SIZE = api.state.get<number>('size', 0.1)!;
+  const SPREAD_BPS = api.state.get<number>('spreadBps', 10)!;
+  const MAX_POS = api.state.get<number>('maxPosition', SIZE * 3)!;
+  const SKEW = api.state.get<number>('skewFactor', 2.0)!;
+
+  let bidOid: number | undefined;
+  let askOid: number | undefined;
+  let bidPrice = 0;
+  let askPrice = 0;
+  let totalBought = 0;
+  let totalSold = 0;
+  let totalBuyCost = 0;
+  let totalSellRevenue = 0;
+
+  const halfSpread = SPREAD_BPS / 10000 / 2;
+
+  api.onStart(() => {
+    api.log.info(`MM Spread: ${COIN} | ${SIZE}/side | ${SPREAD_BPS}bps | Max: ±${MAX_POS}`);
+  });
+
+  api.on('tick', async () => {
+    const mids = await api.client.getAllMids();
+    const mid = parseFloat(mids[COIN]);
+    if (!mid) return;
+
+    // Get position
+    const userState = await api.client.getUserState();
+    const pos = userState.assetPositions.find(p => p.position.coin === COIN);
+    const position = pos ? parseFloat(pos.position.szi) : 0;
+
+    // Check fills
+    const openOrders = await api.client.getOpenOrders();
+    const openOids = new Set(openOrders.filter(o => o.coin === COIN).map(o => o.oid));
+
+    if (bidOid && !openOids.has(bidOid)) {
+      totalBought += SIZE;
+      totalBuyCost += bidPrice * SIZE;
+      api.log.info(`BID FILLED @ ${api.utils.formatUsd(bidPrice)} | Pos: ${position.toFixed(4)}`);
+      bidOid = undefined;
+    }
+    if (askOid && !openOids.has(askOid)) {
+      totalSold += SIZE;
+      totalSellRevenue += askPrice * SIZE;
+      api.log.info(`ASK FILLED @ ${api.utils.formatUsd(askPrice)} | Pos: ${position.toFixed(4)}`);
+      askOid = undefined;
+    }
+
+    // Inventory skew
+    const ratio = Math.max(-1, Math.min(1, position / MAX_POS));
+    const bidSkew = halfSpread * (1 + ratio * SKEW);
+    const askSkew = halfSpread * (1 - ratio * SKEW);
+
+    const targetBid = mid * (1 - Math.max(0.0001, bidSkew));
+    const targetAsk = mid * (1 + Math.max(0.0001, askSkew));
+
+    const shouldBid = position < MAX_POS;
+    const shouldAsk = position > -MAX_POS;
+
+    // Cancel stale quotes
+    if (bidOid) {
+      const drift = Math.abs(bidPrice - targetBid) / mid;
+      if (drift > 0.001 || !shouldBid) {
+        try { await api.client.cancel(COIN, bidOid); } catch { /* */ }
+        bidOid = undefined;
+      }
+    }
+    if (askOid) {
+      const drift = Math.abs(askPrice - targetAsk) / mid;
+      if (drift > 0.001 || !shouldAsk) {
+        try { await api.client.cancel(COIN, askOid); } catch { /* */ }
+        askOid = undefined;
+      }
+    }
+
+    // Place new quotes
+    if (shouldBid && !bidOid) {
+      const resp = await api.client.limitOrder(COIN, true, SIZE, targetBid, 'Gtc', false);
+      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);
+      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; }
+      }
+    }
+  });
+
+  api.onStop(async () => {
+    if (bidOid) try { await api.client.cancel(COIN, bidOid); } catch { /* */ }
+    if (askOid) try { await api.client.cancel(COIN, askOid); } catch { /* */ }
+    const pnl = totalSellRevenue - totalBuyCost;
+    api.log.info(`MM stopped. Bought: ${totalBought.toFixed(6)} | Sold: ${totalSold.toFixed(6)} | PnL: ${api.utils.formatUsd(pnl)}`);
+  });
+}

package/scripts/auto/loader.ts

@@ -3,9 +3,14 @@
 import { existsSync, readdirSync, mkdirSync } from 'fs';
 import path from 'path';
 import os from 'os';
-import type { AutomationFactory } from './types.js';
+import { fileURLToPath } from 'url';
+import type { AutomationFactory, AutomationConfig } from './types.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 const AUTOMATIONS_DIR = path.join(os.homedir(), '.openbroker', 'automations');
+const EXAMPLES_DIR = path.join(__dirname, 'examples');
 
 /** Resolve a script path from a name or path */
 export function resolveScriptPath(nameOrPath: string): string {
@@ -35,6 +40,47 @@ export function resolveScriptPath(nameOrPath: string): string {
   );
 }
 
+/** Resolve a bundled example by name */
+export function resolveExamplePath(name: string): string {
+  const examplePath = path.join(EXAMPLES_DIR, `${name}.ts`);
+  if (!existsSync(examplePath)) {
+    const available = listExamples().map(e => e.name).join(', ');
+    throw new Error(`Unknown example: ${name}\nAvailable: ${available}`);
+  }
+  return examplePath;
+}
+
+/** List bundled example automations */
+export function listExamples(): Array<{ name: string; path: string }> {
+  if (!existsSync(EXAMPLES_DIR)) return [];
+
+  return readdirSync(EXAMPLES_DIR)
+    .filter(f => f.endsWith('.ts') && !f.startsWith('.'))
+    .map(f => ({
+      name: f.replace(/\.ts$/, ''),
+      path: path.join(EXAMPLES_DIR, f),
+    }));
+}
+
+/** Load config metadata from all bundled examples */
+export async function loadExampleConfigs(): Promise<Record<string, AutomationConfig>> {
+  const examples = listExamples();
+  const configs: Record<string, AutomationConfig> = {};
+
+  for (const example of examples) {
+    try {
+      const mod = await import(example.path);
+      if (mod.config && typeof mod.config === 'object' && mod.config.description) {
+        configs[example.name] = mod.config as AutomationConfig;
+      }
+    } catch {
+      // Skip examples that fail to load
+    }
+  }
+
+  return configs;
+}
+
 /** Load an automation module and validate the default export */
 export async function loadAutomation(scriptPath: string): Promise<AutomationFactory> {
   const absolutePath = path.resolve(scriptPath);

package/scripts/auto/runtime.ts

@@ -231,6 +231,8 @@ export interface RuntimeOptions {
   gatewayPort?: number;
   /** Hooks token for webhook auth. Falls back to OPENCLAW_HOOKS_TOKEN */
   hooksToken?: string;
+  /** Pre-seed state before the factory function runs (e.g. from --set key=value) */
+  initialState?: Record<string, unknown>;
 }
 
 /** Registry of all running automations */
@@ -255,6 +257,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     pollIntervalMs = 10_000,
     gatewayPort,
     hooksToken,
+    initialState,
   } = options;
 
   const id = options.id || path.basename(scriptPath, '.ts');
@@ -265,6 +268,16 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
 
   const log = createLogger(id, verbose);
   const state = createState(id);
+
+  // Pre-seed state from --set flags (doesn't overwrite already-persisted keys)
+  if (initialState) {
+    for (const [key, value] of Object.entries(initialState)) {
+      if (state.get(key) === undefined) {
+        state.set(key, value);
+      }
+    }
+  }
+
   const eventBus = new AutomationEventBus();
 
   const rawClient = getClient();

package/scripts/auto/types.ts

@@ -8,6 +8,20 @@ import type { HyperliquidClient } from '../core/client.js';
 /** What an automation .ts file exports */
 export type AutomationFactory = (api: AutomationAPI) => void | Promise<void>;
 
+/** Config field descriptor for example automations */
+export interface AutomationConfigField {
+  type: 'string' | 'number' | 'boolean';
+  description: string;
+  default: unknown;
+  required?: boolean;
+}
+
+/** Config metadata exported by example automations as `export const config` */
+export interface AutomationConfig {
+  description: string;
+  fields: Record<string, AutomationConfigField>;
+}
+
 // ── Event system ────────────────────────────────────────────────────
 
 export type AutomationEventType =

package/scripts/info/orders.ts

@@ -11,11 +11,14 @@ Usage: openbroker orders [options]
 Options:
   --coin <symbol>     Filter by coin (e.g. ETH, BTC)
   --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)
   --help, -h          Show this help
 
 Examples:
   openbroker orders
+  openbroker orders --open
+  openbroker orders --open --coin ETH
   openbroker orders --coin ETH --status filled
   openbroker orders --top 50
 `);
@@ -31,11 +34,78 @@ async function main() {
 
   const filterCoin = args.coin as string | undefined;
   const filterStatus = args.status as string | undefined;
+  const openOnly = args.open as boolean;
   const top = parseInt(args.top as string) || 20;
   const jsonOutput = args.json as boolean;
   const client = getClient();
 
   try {
+    if (openOnly) {
+      // Use the dedicated open orders endpoint
+      let openOrders = await client.getOpenOrders();
+
+      if (filterCoin) {
+        openOrders = openOrders.filter(o => o.coin === normalizeCoin(filterCoin));
+      }
+
+      openOrders.sort((a, b) => b.timestamp - a.timestamp);
+      openOrders = openOrders.slice(0, top);
+
+      if (jsonOutput) {
+        console.log(JSON.stringify(openOrders.map(o => ({
+          time: new Date(o.timestamp).toISOString(),
+          coin: o.coin,
+          side: o.side === 'B' ? 'buy' : 'sell',
+          orderType: o.orderType,
+          size: o.sz,
+          origSize: o.origSz,
+          price: o.limitPx,
+          status: 'open',
+          oid: o.oid,
+        })), null, 2));
+        return;
+      }
+
+      console.log('Open Broker - Open Orders');
+      console.log('=========================\n');
+
+      if (openOrders.length === 0) {
+        console.log('No open orders found');
+        return;
+      }
+
+      // Table header
+      console.log(
+        'Time'.padEnd(20) +
+        'Coin'.padEnd(10) +
+        'Side'.padEnd(6) +
+        'Type'.padEnd(14) +
+        'Size'.padEnd(12) +
+        'Price'.padEnd(14) +
+        'OID'
+      );
+      console.log('─'.repeat(90));
+
+      for (const o of openOrders) {
+        const time = new Date(o.timestamp).toLocaleString();
+        const side = o.side === 'B' ? 'BUY' : 'SELL';
+
+        console.log(
+          time.padEnd(20) +
+          o.coin.padEnd(10) +
+          side.padEnd(6) +
+          o.orderType.padEnd(14) +
+          o.sz.padEnd(12) +
+          formatUsd(parseFloat(o.limitPx)).padEnd(14) +
+          String(o.oid)
+        );
+      }
+
+      console.log('─'.repeat(90));
+      console.log(`Showing ${openOrders.length} open orders`);
+      return;
+    }
+
     let orders = await client.getHistoricalOrders();
 
     if (filterCoin) {