openbroker 1.0.67 → 1.0.69

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/plugin/tools.ts

@@ -1344,23 +1344,34 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
 
     {
       name: 'ob_auto_run',
-      description: 'Start a trading automation script. Scripts are TypeScript files that export a default factory function with event handlers (price_change, funding_update, position_opened, etc.). Scripts are loaded from ~/.openbroker/automations/ or an absolute path.',
+      description: 'Start a trading automation script. Scripts are TypeScript files that export a default factory function with event handlers (price_change, funding_update, position_opened, etc.). Scripts are loaded from ~/.openbroker/automations/, an absolute path, or bundled examples (dca, grid, funding-arb, mm-spread, mm-maker).',
       parameters: {
         type: 'object',
         properties: {
           script: { type: 'string', description: 'Script name (from ~/.openbroker/automations/) or absolute path' },
+          example: { type: 'string', description: 'Bundled example name: dca, grid, funding-arb, mm-spread, mm-maker' },
+          config: { type: 'object', description: 'Key-value config to pre-seed automation state (e.g. { coin: "BTC", amount: 50 })' },
           id: { type: 'string', description: 'Custom automation ID (default: filename)' },
           dry: { type: 'boolean', description: 'Intercept write methods — no real trades' },
           poll: { type: 'number', description: 'Poll interval in milliseconds (default: 10000)' },
         },
-        required: ['script'],
       },
       async execute(_id, params) {
         try {
-          const { resolveScriptPath } = await import('../auto/loader.js');
+          const { resolveScriptPath, resolveExamplePath } = await import('../auto/loader.js');
           const { startAutomation } = await import('../auto/runtime.js');
 
-          const scriptPath = resolveScriptPath(String(params.script));
+          if (!params.script && !params.example) {
+            return error('Either "script" or "example" parameter is required');
+          }
+
+          const scriptPath = params.example
+            ? resolveExamplePath(String(params.example))
+            : resolveScriptPath(String(params.script));
+          const initialState = params.config && typeof params.config === 'object'
+            ? params.config as Record<string, unknown>
+            : undefined;
+
           const automation = await startAutomation({
             scriptPath,
             id: params.id ? String(params.id) : undefined,
@@ -1368,6 +1379,7 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
             pollIntervalMs: params.poll ? Number(params.poll) : 10_000,
             gatewayPort,
             hooksToken,
+            initialState,
           });
 
           return json({
@@ -1409,13 +1421,14 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
 
     {
       name: 'ob_auto_list',
-      description: 'List available automation scripts and running automations (including those started from other processes)',
+      description: 'List available automation scripts, bundled examples (dca, grid, funding-arb, mm-spread, mm-maker), and running automations',
       parameters: { type: 'object', properties: {} },
       async execute() {
-        const { listAutomations } = await import('../auto/loader.js');
+        const { listAutomations, loadExampleConfigs } = await import('../auto/loader.js');
         const { getRunningAutomations, getRegisteredAutomations } = await import('../auto/runtime.js');
 
         const available = listAutomations();
+        const examples = await loadExampleConfigs();
 
         // In-process automations with live stats
         const inProcess = getRunningAutomations().map(a => ({
@@ -1443,7 +1456,7 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
             source: 'other_process',
           }));
 
-        return json({ available, running: [...inProcess, ...external] });
+        return json({ available, examples, running: [...inProcess, ...external] });
       },
     },
   ];