openbroker 1.0.60 → 1.0.61

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: openbroker
-description: Hyperliquid trading plugin with background position monitoring. Execute market orders, limit orders, manage positions, view funding rates, and run trading strategies with automatic alerts for PnL changes and liquidation risk.
+description: Hyperliquid trading plugin with background position monitoring and custom automations. Execute market orders, limit orders, manage positions, view funding rates, run trading strategies, and write event-driven automation scripts with automatic alerts for PnL changes and liquidation risk.
 license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.0.60", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
-allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status Bash(openbroker:*)
+metadata: {"author": "monemetrics", "version": "1.0.61", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
+allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI
@@ -66,6 +66,9 @@ If an `ob_*` plugin tool returns unexpected errors, empty results, or crashes, *
 | `ob_orders` | `openbroker orders --json` |
 | `ob_funding_scan` | `openbroker funding-scan --json` |
 | `ob_candles` | `openbroker candles --coin <COIN> --json` |
+| `ob_auto_run` | `openbroker auto run <script> [--dry]` |
+| `ob_auto_stop` | (stop via SIGINT when using CLI) |
+| `ob_auto_list` | `openbroker auto list` |
 
 **When to use CLI fallback:**
 - Plugin tool returns `null`, empty data, or throws an error
@@ -448,6 +451,7 @@ This skill works standalone via Bash — every command above runs through the `o
 
 - **Structured agent tools** (`ob_account`, `ob_buy`, `ob_limit`, etc.) — typed tool calls with proper input schemas instead of Bash strings. The agent gets structured JSON responses.
 - **Background position watcher** — polls your Hyperliquid account every 30s and sends webhook alerts when positions open/close, PnL moves significantly, or margin usage gets dangerous.
+- **Automation tools** (`ob_auto_run`, `ob_auto_stop`, `ob_auto_list`) — start, stop, and manage custom trading automations from within the agent.
 - **CLI commands** — `openclaw ob status` and `openclaw ob watch` for inspecting the watcher.
 
 ### Enable the plugin
@@ -487,6 +491,199 @@ Without hooks, the watcher still runs and tracks state (accessible via `ob_watch
 - **Skill only (no plugin):** Use Bash commands (`openbroker buy --coin ETH --size 0.1`). No background monitoring.
 - **Skill + plugin:** The agent prefers the `ob_*` tools when available (structured data), falls back to Bash for commands not covered by tools (strategies, scale). Background watcher sends alerts automatically.
 
+## Trading Automations
+
+Automations let you write custom event-driven trading logic as TypeScript scripts. Instead of using the rigid built-in strategies, write exactly the logic you need and OpenBroker handles the polling, event detection, and SDK access.
+
+### How Automations Work
+
+An automation is a `.ts` file that exports a default function. The function receives an `AutomationAPI` with the full Hyperliquid client, typed event subscriptions, persistent state, and a logger. The runtime polls Hyperliquid every 10s (configurable) and dispatches events when changes are detected.
+
+### Writing an Automation
+
+Create a `.ts` file in `~/.openbroker/automations/` (or any path):
+
+```typescript
+// ~/.openbroker/automations/funding-scalp.ts
+export default function(api) {
+  const COIN = 'ETH';
+
+  api.on('funding_update', async ({ coin, annualized }) => {
+    if (coin !== COIN) return;
+
+    if (annualized > 0.5 && !api.state.get('isShort')) {
+      api.log.info('High positive funding — going short');
+      await api.client.marketOrder(COIN, false, 0.1);
+      api.state.set('isShort', true);
+    } else if (annualized < -0.1 && api.state.get('isShort')) {
+      api.log.info('Funding normalized — closing short');
+      await api.client.marketOrder(COIN, true, 0.1);
+      api.state.set('isShort', false);
+    }
+  });
+
+  api.onStop(async () => {
+    if (api.state.get('isShort')) {
+      api.log.warn('Closing short on shutdown');
+      await api.client.marketOrder('ETH', true, 0.1);
+      api.state.set('isShort', false);
+    }
+  });
+}
+```
+
+### AutomationAPI Reference
+
+| Property / Method | Description |
+|-------------------|-------------|
+| `api.client` | Full HyperliquidClient — `marketOrder()`, `limitOrder()`, `triggerOrder()`, `cancelAll()`, `getUserStateAll()`, `getAllMids()`, `updateLeverage()`, and 35+ more methods |
+| `api.on(event, handler)` | Subscribe to a market/account event (see Events below) |
+| `api.every(ms, handler)` | Run a handler on a recurring interval (aligned to poll loop) |
+| `api.onStart(handler)` | Called after all handlers are registered, before first poll |
+| `api.onStop(handler)` | Called on shutdown (SIGINT). Use for cleanup — close positions, cancel orders |
+| `api.onError(handler)` | Called when a handler throws. Error is already logged — use for recovery logic |
+| `api.state.get(key)` | Get a persisted value (survives restarts, stored in `~/.openbroker/state/`) |
+| `api.state.set(key, value)` | Set a persisted value |
+| `api.state.delete(key)` | Delete a persisted value |
+| `api.state.clear()` | Clear all state |
+| `api.log.info/warn/error/debug(msg)` | Structured logger |
+| `api.utils` | `roundPrice`, `roundSize`, `sleep`, `normalizeCoin`, `formatUsd`, `annualizeFundingRate` |
+| `api.id` | Automation ID (filename or `--id` flag) |
+| `api.dryRun` | `true` if running with `--dry` (write methods are intercepted) |
+
+### Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `tick` | `{ timestamp, pollCount }` | Every poll cycle (default: 10s) |
+| `price_change` | `{ coin, oldPrice, newPrice, changePct }` | Mid price moved > 0.1% |
+| `funding_update` | `{ coin, fundingRate, annualized, premium }` | Every poll for all assets |
+| `position_opened` | `{ coin, side, size, entryPrice }` | New position detected |
+| `position_closed` | `{ coin, previousSize, entryPrice }` | Position no longer present |
+| `position_changed` | `{ coin, oldSize, newSize, entryPrice }` | Position size changed |
+| `pnl_threshold` | `{ coin, unrealizedPnl, changePct, positionValue }` | PnL moved > 5% of position value |
+| `margin_warning` | `{ marginUsedPct, equity, marginUsed }` | Margin usage > 80% |
+
+### Client Methods Available
+
+The `api.client` object exposes the full Hyperliquid SDK:
+
+**Trading:** `marketOrder(coin, isBuy, size)`, `limitOrder(coin, isBuy, size, price)`, `triggerOrder(coin, isBuy, size, triggerPx, isMarket)`, `takeProfit(coin, isBuy, size, triggerPx)`, `stopLoss(coin, isBuy, size, triggerPx)`, `cancel(coin, oid)`, `cancelAll(coin?)`
+
+**Market Data:** `getAllMids()`, `getMetaAndAssetCtxs()`, `getRecentTrades(coin)`, `getCandleSnapshot(coin, interval)`, `getFundingHistory(coin)`, `getPredictedFundings()`
+
+**Account:** `getUserStateAll()`, `getOpenOrders()`, `getUserFills()`, `getUserFunding()`, `getHistoricalOrders()`, `getUserFees()`, `getUserRateLimit()`, `getSpotBalances()`
+
+**Leverage:** `updateLeverage(coin, leverage, isIsolated?)`
+
+### Example: Price Breakout
+
+```typescript
+// ~/.openbroker/automations/breakout.ts
+export default function(api) {
+  const COIN = 'ETH';
+  const BREAKOUT_PCT = 2;  // 2% move triggers entry
+  const SIZE = 0.5;
+  let basePrice = null;
+
+  api.onStart(async () => {
+    const mids = await api.client.getAllMids();
+    basePrice = parseFloat(mids[COIN]);
+    api.log.info(`Watching ${COIN} from $${basePrice} for ${BREAKOUT_PCT}% breakout`);
+  });
+
+  api.on('price_change', async ({ coin, newPrice }) => {
+    if (coin !== COIN || !basePrice) return;
+    const totalChange = ((newPrice - basePrice) / basePrice) * 100;
+
+    if (Math.abs(totalChange) >= BREAKOUT_PCT && !api.state.get('inPosition')) {
+      const side = totalChange > 0;  // true = long, false = short
+      api.log.info(`Breakout! ${totalChange.toFixed(2)}% — entering ${side ? 'long' : 'short'}`);
+      await api.client.marketOrder(COIN, side, SIZE);
+      api.state.set('inPosition', true);
+    }
+  });
+}
+```
+
+### Example: Scheduled DCA
+
+```typescript
+// ~/.openbroker/automations/hourly-dca.ts
+export default function(api) {
+  const COIN = 'ETH';
+  const USD_PER_BUY = 100;
+
+  // Buy $100 of ETH every hour
+  api.every(60 * 60 * 1000, async () => {
+    const mids = await api.client.getAllMids();
+    const price = parseFloat(mids[COIN]);
+    const size = parseFloat(api.utils.roundSize(USD_PER_BUY / price, 4));
+    await api.client.marketOrder(COIN, true, size);
+    const count = (api.state.get('buyCount') || 0) + 1;
+    api.state.set('buyCount', count);
+    api.log.info(`DCA #${count}: bought ${size} ${COIN} at $${price}`);
+  });
+}
+```
+
+### Example: Margin Guardian
+
+```typescript
+// ~/.openbroker/automations/margin-guard.ts
+export default function(api) {
+  api.on('margin_warning', async ({ marginUsedPct, equity }) => {
+    api.log.warn(`Margin at ${marginUsedPct.toFixed(1)}% — reducing positions`);
+
+    // Close the smallest position to free margin
+    const state = await api.client.getUserStateAll();
+    const positions = state.assetPositions
+      .filter(p => parseFloat(p.position.szi) !== 0)
+      .sort((a, b) => Math.abs(parseFloat(a.position.positionValue)) - Math.abs(parseFloat(b.position.positionValue)));
+
+    if (positions.length > 0) {
+      const pos = positions[0].position;
+      const size = Math.abs(parseFloat(pos.szi));
+      const isBuy = parseFloat(pos.szi) < 0; // Close short = buy, close long = sell
+      api.log.info(`Closing smallest position: ${pos.coin} (${pos.szi})`);
+      await api.client.marketOrder(pos.coin, isBuy, size);
+    }
+  });
+}
+```
+
+### Running Automations
+
+**CLI:**
+```bash
+openbroker auto run my-strategy --dry       # Test without trading
+openbroker auto run ./funding-scalp.ts      # Run from path
+openbroker auto run my-strategy --poll 5000 # Poll every 5s
+openbroker auto list                        # Show available scripts
+openbroker auto status                      # Show running automations
+```
+
+**Plugin tools (for OpenClaw agents):**
+- `ob_auto_run` — `{ "script": "funding-scalp", "dry": true }` — start an automation
+- `ob_auto_stop` — `{ "id": "funding-scalp" }` — stop a running automation
+- `ob_auto_list` — `{}` — list available and running automations
+
+**Options:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry` | Intercept write methods — no real trades | false |
+| `--verbose` | Show debug output | false |
+| `--id <name>` | Custom automation ID | filename |
+| `--poll <ms>` | Poll interval in milliseconds | 10000 |
+
+**Important notes for agents writing automations:**
+- Always test with `--dry` first before live trading
+- Use `api.state` to track position state across restarts
+- Use `api.onStop()` to clean up — close positions, cancel orders
+- The runtime catches errors per handler — one failing handler won't crash others
+- Scripts are loaded from `~/.openbroker/automations/` by name, or from any absolute path
+- All trading commands support HIP-3 assets (`api.client.marketOrder('xyz:CL', true, 1)`)
+
 ## Risk Warning
 
 - Always use `--dry` first to preview orders

package/bin/cli.ts

@@ -52,6 +52,9 @@ const commands: Record<string, { script: string; description: string }> = {
   'dca': { script: 'strategies/dca.ts', description: 'DCA strategy' },
   'mm-spread': { script: 'strategies/mm-spread.ts', description: 'Market making (spread)' },
   'mm-maker': { script: 'strategies/mm-maker.ts', description: 'Market making (ALO)' },
+
+  // Automations
+  'auto': { script: 'auto/cli.ts', description: 'Run/manage trading automations' },
 };
 
 function printHelp() {
@@ -103,6 +106,11 @@ Strategies:
   mm-spread            Market making (spread-based)
   mm-maker             Market making (ALO orders)
 
+Automations:
+  auto run <script>    Run a custom trading automation
+  auto list            List available automations
+  auto status          Show running automations
+
 Options:
   --help, -h           Show help for a command
   --dry                Preview without executing

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.60",
+  "version": "1.0.61",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {

package/scripts/auto/cli.ts

@@ -0,0 +1,172 @@
+// CLI entry point for `openbroker auto` commands
+
+import { parseArgs } from '../core/utils.js';
+import { resolveScriptPath, listAutomations, ensureAutomationsDir } from './loader.js';
+import { startAutomation, getRunningAutomations } from './runtime.js';
+
+function printUsage() {
+  console.log(`
+OpenBroker Automations — event-driven trading scripts
+
+Usage:
+  openbroker auto run <script> [options]    Run an automation script
+  openbroker auto list                      List available automations
+  openbroker auto status                    Show running automations
+
+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)
+
+Scripts are loaded from:
+  1. Absolute or relative path
+  2. ~/.openbroker/automations/<name>.ts
+
+Writing an automation:
+  export default function(api) {
+    api.on('price_change', async ({ coin, changePct }) => {
+      api.log.info(\`\${coin} moved \${changePct.toFixed(2)}%\`);
+    });
+  }
+
+Events: tick, price_change, funding_update, position_opened,
+        position_closed, position_changed, pnl_threshold, margin_warning
+
+Examples:
+  openbroker auto run my-strategy --dry     # Test without trading
+  openbroker auto run ./funding-scalp.ts    # Run from path
+  openbroker auto list                      # Show available scripts
+`);
+}
+
+async function runCommand(args: Record<string, string | boolean>, positional: string[]) {
+  const scriptName = positional[0];
+  if (!scriptName) {
+    console.error('Error: script name or path required');
+    console.log('Usage: openbroker auto run <script> [--dry] [--verbose]');
+    process.exit(1);
+  }
+
+  const scriptPath = resolveScriptPath(scriptName);
+  const dryRun = args.dry === true;
+  const verbose = args.verbose === true;
+  const pollIntervalMs = args.poll ? parseInt(String(args.poll), 10) : 10_000;
+  const id = args.id ? String(args.id) : undefined;
+
+  if (isNaN(pollIntervalMs) || pollIntervalMs < 1000) {
+    console.error('Error: --poll must be at least 1000ms');
+    process.exit(1);
+  }
+
+  const automation = await startAutomation({
+    scriptPath,
+    id,
+    dryRun,
+    verbose,
+    pollIntervalMs,
+  });
+
+  // Graceful shutdown on SIGINT/SIGTERM
+  const shutdown = async () => {
+    console.log('\nShutting down...');
+    await automation.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Keep process alive
+  await new Promise(() => {});
+}
+
+function listCommand() {
+  ensureAutomationsDir();
+  const automations = listAutomations();
+
+  if (automations.length === 0) {
+    console.log('No automations found in ~/.openbroker/automations/');
+    console.log('\nCreate a .ts file there with:');
+    console.log('  export default function(api) { ... }');
+    return;
+  }
+
+  console.log('Available automations:\n');
+  for (const a of automations) {
+    console.log(`  ${a.name.padEnd(30)} ${a.path}`);
+  }
+  console.log(`\nRun with: openbroker auto run <name>`);
+}
+
+function statusCommand() {
+  const running = getRunningAutomations();
+
+  if (running.length === 0) {
+    console.log('No automations running');
+    return;
+  }
+
+  console.log('Running automations:\n');
+  for (const a of running) {
+    const uptime = Math.round((Date.now() - a.startedAt.getTime()) / 1000);
+    console.log(`  ${a.id}`);
+    console.log(`    Script:  ${a.scriptPath}`);
+    console.log(`    Uptime:  ${uptime}s`);
+    console.log(`    Polls:   ${a.pollCount}`);
+    console.log(`    Events:  ${a.eventsEmitted}`);
+    console.log(`    Dry run: ${a.dryRun}`);
+    console.log('');
+  }
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+
+  if (rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const subcommand = rawArgs[0];
+  const restArgs = rawArgs.slice(1);
+
+  // Extract positional args (non-flag args)
+  const positional: string[] = [];
+  const flagArgs: string[] = [];
+  for (let i = 0; i < restArgs.length; i++) {
+    if (restArgs[i].startsWith('--')) {
+      flagArgs.push(restArgs[i]);
+      // If next arg doesn't start with --, it's a flag value
+      if (i + 1 < restArgs.length && !restArgs[i + 1].startsWith('--')) {
+        flagArgs.push(restArgs[i + 1]);
+        i++;
+      }
+    } else {
+      positional.push(restArgs[i]);
+    }
+  }
+
+  const args = parseArgs(flagArgs);
+
+  switch (subcommand) {
+    case 'run':
+      await runCommand(args, positional);
+      break;
+    case 'list':
+      listCommand();
+      break;
+    case 'status':
+      statusCommand();
+      break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      console.log('Run "openbroker auto --help" for usage');
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/scripts/auto/events.ts

@@ -0,0 +1,52 @@
+// Lightweight typed event bus for the automation runtime
+
+import type {
+  AutomationEventType,
+  AutomationEventPayloads,
+  AutomationEventHandler,
+} from './types.js';
+
+export class AutomationEventBus {
+  private handlers = new Map<AutomationEventType, Set<Function>>();
+
+  on<E extends AutomationEventType>(
+    event: E,
+    handler: AutomationEventHandler<E>,
+  ): void {
+    let set = this.handlers.get(event);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(event, set);
+    }
+    set.add(handler);
+  }
+
+  /** Emit an event — handlers run sequentially, errors are returned (not thrown) */
+  async emit<E extends AutomationEventType>(
+    event: E,
+    payload: AutomationEventPayloads[E],
+  ): Promise<Error[]> {
+    const set = this.handlers.get(event);
+    if (!set || set.size === 0) return [];
+
+    const errors: Error[] = [];
+    for (const handler of set) {
+      try {
+        await handler(payload);
+      } catch (err) {
+        errors.push(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+    return errors;
+  }
+
+  /** Check if any handlers are registered for an event */
+  has(event: AutomationEventType): boolean {
+    const set = this.handlers.get(event);
+    return set !== undefined && set.size > 0;
+  }
+
+  removeAll(): void {
+    this.handlers.clear();
+  }
+}

package/scripts/auto/loader.ts

@@ -0,0 +1,71 @@
+// Automation script loader — discovers and loads .ts automation files
+
+import { existsSync, readdirSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import type { AutomationFactory } from './types.js';
+
+const AUTOMATIONS_DIR = path.join(os.homedir(), '.openbroker', 'automations');
+
+/** Resolve a script path from a name or path */
+export function resolveScriptPath(nameOrPath: string): string {
+  // Absolute path
+  if (path.isAbsolute(nameOrPath)) {
+    if (!existsSync(nameOrPath)) {
+      throw new Error(`Automation script not found: ${nameOrPath}`);
+    }
+    return nameOrPath;
+  }
+
+  // Relative to cwd
+  const cwdPath = path.resolve(process.cwd(), nameOrPath);
+  if (existsSync(cwdPath)) return cwdPath;
+
+  // Relative to ~/.openbroker/automations/
+  const globalPath = path.join(AUTOMATIONS_DIR, nameOrPath);
+  if (existsSync(globalPath)) return globalPath;
+
+  // Try appending .ts
+  const withExt = path.join(AUTOMATIONS_DIR, `${nameOrPath}.ts`);
+  if (existsSync(withExt)) return withExt;
+
+  throw new Error(
+    `Automation script not found: ${nameOrPath}\n` +
+    `Searched:\n  ${cwdPath}\n  ${globalPath}\n  ${withExt}`,
+  );
+}
+
+/** Load an automation module and validate the default export */
+export async function loadAutomation(scriptPath: string): Promise<AutomationFactory> {
+  const absolutePath = path.resolve(scriptPath);
+
+  // Dynamic import — tsx handles TypeScript transpilation
+  const mod = await import(absolutePath);
+
+  const factory = mod.default;
+  if (typeof factory !== 'function') {
+    throw new Error(
+      `Automation script must export a default function.\n` +
+      `Got: ${typeof factory} from ${scriptPath}`,
+    );
+  }
+
+  return factory as AutomationFactory;
+}
+
+/** List available automation scripts in ~/.openbroker/automations/ */
+export function listAutomations(): Array<{ name: string; path: string }> {
+  if (!existsSync(AUTOMATIONS_DIR)) return [];
+
+  return readdirSync(AUTOMATIONS_DIR)
+    .filter(f => f.endsWith('.ts') && !f.startsWith('.'))
+    .map(f => ({
+      name: f.replace(/\.ts$/, ''),
+      path: path.join(AUTOMATIONS_DIR, f),
+    }));
+}
+
+/** Ensure the automations directory exists */
+export function ensureAutomationsDir(): void {
+  mkdirSync(AUTOMATIONS_DIR, { recursive: true });
+}

package/scripts/auto/runtime.ts

@@ -0,0 +1,447 @@
+// Automation Runtime — loads scripts, polls market data, dispatches events
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { getClient } from '../core/client.js';
+import type { HyperliquidClient } from '../core/client.js';
+import {
+  roundPrice, roundSize, sleep, normalizeCoin,
+  formatUsd, formatPercent, annualizeFundingRate,
+} from '../core/utils.js';
+import { AutomationEventBus } from './events.js';
+import { loadAutomation } from './loader.js';
+import type {
+  AutomationAPI,
+  AutomationLogger,
+  AutomationState,
+  AutomationSnapshot,
+  PositionSnapshot,
+  ScheduledTask,
+  RunningAutomation,
+} from './types.js';
+
+const STATE_DIR = path.join(os.homedir(), '.openbroker', 'state');
+
+// ── State persistence ───────────────────────────────────────────────
+
+function createState(id: string): AutomationState {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const stateFile = path.join(STATE_DIR, `${id}.json`);
+
+  let data: Record<string, unknown> = {};
+  if (existsSync(stateFile)) {
+    try {
+      data = JSON.parse(readFileSync(stateFile, 'utf-8'));
+    } catch {
+      data = {};
+    }
+  }
+
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  function scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      writeFileSync(stateFile, JSON.stringify(data, null, 2));
+    }, 500);
+  }
+
+  return {
+    get<T = unknown>(key: string, defaultValue?: T): T | undefined {
+      return (key in data ? data[key] : defaultValue) as T | undefined;
+    },
+    set<T = unknown>(key: string, value: T): void {
+      data[key] = value;
+      scheduleFlush();
+    },
+    delete(key: string): void {
+      delete data[key];
+      scheduleFlush();
+    },
+    clear(): void {
+      data = {};
+      scheduleFlush();
+    },
+  };
+}
+
+// ── Logger ──────────────────────────────────────────────────────────
+
+function createLogger(id: string, verbose: boolean): AutomationLogger {
+  const prefix = `[auto:${id}]`;
+  return {
+    info: (msg: string) => console.log(`${prefix} ${msg}`),
+    warn: (msg: string) => console.log(`${prefix} ⚠ ${msg}`),
+    error: (msg: string) => console.error(`${prefix} ✗ ${msg}`),
+    debug: (msg: string) => { if (verbose) console.log(`${prefix} … ${msg}`); },
+  };
+}
+
+// ── Dry-run client proxy ────────────────────────────────────────────
+
+const WRITE_METHODS = new Set([
+  'order', 'marketOrder', 'limitOrder', 'triggerOrder',
+  'takeProfit', 'stopLoss', 'cancel', 'cancelAll',
+  'updateLeverage', 'approveBuilderFee',
+]);
+
+function createDryClient(client: HyperliquidClient, log: AutomationLogger): HyperliquidClient {
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof prop === 'string' && WRITE_METHODS.has(prop) && typeof value === 'function') {
+        return (...args: unknown[]) => {
+          log.info(`[DRY] ${prop}(${args.map(a => JSON.stringify(a)).join(', ')})`);
+          return Promise.resolve({ status: 'ok', response: { type: 'dry_run' } });
+        };
+      }
+      return value;
+    },
+  });
+}
+
+// ── Snapshot building ───────────────────────────────────────────────
+
+async function buildSnapshot(
+  client: HyperliquidClient,
+): Promise<AutomationSnapshot> {
+  const [state, mids, metaCtxs] = await Promise.all([
+    client.getUserStateAll(),
+    client.getAllMids(),
+    client.getMetaAndAssetCtxs(),
+  ]);
+
+  const prices = new Map<string, number>();
+  for (const [coin, mid] of Object.entries(mids)) {
+    prices.set(coin, parseFloat(mid as string));
+  }
+
+  const positions = new Map<string, PositionSnapshot>();
+  for (const ap of state.assetPositions) {
+    const p = ap.position;
+    const size = parseFloat(p.szi);
+    if (size === 0) continue;
+    positions.set(p.coin, {
+      coin: p.coin,
+      size,
+      entryPrice: parseFloat(p.entryPx),
+      positionValue: parseFloat(p.positionValue),
+      unrealizedPnl: parseFloat(p.unrealizedPnl),
+      liquidationPx: p.liquidationPx ? parseFloat(p.liquidationPx) : null,
+      leverage: typeof p.leverage === 'object' ? p.leverage.value : parseFloat(String(p.leverage)),
+      marginUsed: parseFloat(p.marginUsed),
+    });
+  }
+
+  const equity = parseFloat(state.marginSummary.accountValue);
+  const marginUsed = parseFloat(state.marginSummary.totalMarginUsed);
+
+  // Build funding rates from asset contexts
+  const fundingRates = new Map<string, { rate: number; premium: number }>();
+  if (metaCtxs && Array.isArray(metaCtxs)) {
+    for (const group of metaCtxs) {
+      if (!group.universe || !group.assetCtxs) continue;
+      for (let i = 0; i < group.universe.length; i++) {
+        const meta = group.universe[i];
+        const ctx = group.assetCtxs[i];
+        if (ctx && meta) {
+          fundingRates.set(meta.name, {
+            rate: parseFloat(ctx.funding || '0'),
+            premium: parseFloat(ctx.premium || '0'),
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    prices,
+    positions,
+    openOrderIds: new Set(), // filled by separate call if needed
+    equity,
+    marginUsed,
+    marginUsedPct: equity > 0 ? (marginUsed / equity) * 100 : 0,
+    fundingRates,
+    timestamp: Date.now(),
+  };
+}
+
+// ── Runtime ─────────────────────────────────────────────────────────
+
+export interface RuntimeOptions {
+  scriptPath: string;
+  id?: string;
+  dryRun?: boolean;
+  verbose?: boolean;
+  pollIntervalMs?: number;
+}
+
+/** Registry of all running automations */
+const registry = new Map<string, RunningAutomation>();
+
+export function getRunningAutomations(): RunningAutomation[] {
+  return [...registry.values()];
+}
+
+export function getAutomation(id: string): RunningAutomation | undefined {
+  return registry.get(id);
+}
+
+export async function startAutomation(options: RuntimeOptions): Promise<RunningAutomation> {
+  const {
+    scriptPath,
+    dryRun = false,
+    verbose = false,
+    pollIntervalMs = 10_000,
+  } = options;
+
+  const id = options.id || path.basename(scriptPath, '.ts');
+
+  if (registry.has(id)) {
+    throw new Error(`Automation "${id}" is already running`);
+  }
+
+  const log = createLogger(id, verbose);
+  const state = createState(id);
+  const eventBus = new AutomationEventBus();
+
+  const rawClient = getClient();
+  const client = dryRun ? createDryClient(rawClient, log) : rawClient;
+
+  const startHooks: Array<() => void | Promise<void>> = [];
+  const stopHooks: Array<() => void | Promise<void>> = [];
+  const errorHooks: Array<(err: Error) => void | Promise<void>> = [];
+  const scheduledTasks: ScheduledTask[] = [];
+
+  // Build the API object
+  const api: AutomationAPI = {
+    client,
+    utils: { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate },
+    on: (event, handler) => eventBus.on(event, handler),
+    every: (intervalMs, handler) => scheduledTasks.push({ intervalMs, handler, lastRun: 0 }),
+    onStart: (handler) => startHooks.push(handler),
+    onStop: (handler) => stopHooks.push(handler),
+    onError: (handler) => errorHooks.push(handler),
+    state,
+    log,
+    id,
+    dryRun,
+  };
+
+  // Load and execute the factory function (registers handlers)
+  log.info(`Loading automation: ${scriptPath}`);
+  const factory = await loadAutomation(scriptPath);
+  await factory(api);
+
+  // Call onStart hooks
+  for (const hook of startHooks) {
+    try { await hook(); } catch (err) {
+      log.error(`onStart hook error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Polling state
+  let previousSnapshot: AutomationSnapshot | null = null;
+  let pollCount = 0;
+  let eventsEmitted = 0;
+  let isPolling = false;
+  let stopped = false;
+
+  async function handleErrors(errors: Error[]) {
+    for (const err of errors) {
+      log.error(`Handler error: ${err.message}`);
+      for (const hook of errorHooks) {
+        try { await hook(err); } catch { /* swallow */ }
+      }
+    }
+  }
+
+  async function poll() {
+    if (isPolling || stopped) return;
+    isPolling = true;
+
+    try {
+      const snapshot = await buildSnapshot(rawClient);
+      pollCount++;
+      const now = Date.now();
+
+      // Always emit tick
+      const tickErrors = await eventBus.emit('tick', { timestamp: now, pollCount });
+      if (tickErrors.length) await handleErrors(tickErrors);
+      eventsEmitted++;
+
+      if (previousSnapshot) {
+        // Price changes
+        if (eventBus.has('price_change')) {
+          for (const [coin, newPrice] of snapshot.prices) {
+            const oldPrice = previousSnapshot.prices.get(coin);
+            if (oldPrice === undefined || oldPrice === 0) continue;
+            const changePct = ((newPrice - oldPrice) / oldPrice) * 100;
+            if (Math.abs(changePct) >= 0.1) { // 0.1% minimum to fire
+              const errors = await eventBus.emit('price_change', { coin, oldPrice, newPrice, changePct });
+              if (errors.length) await handleErrors(errors);
+              eventsEmitted++;
+            }
+          }
+        }
+
+        // Funding updates
+        if (eventBus.has('funding_update')) {
+          for (const [coin, data] of snapshot.fundingRates) {
+            const errors = await eventBus.emit('funding_update', {
+              coin,
+              fundingRate: data.rate,
+              annualized: annualizeFundingRate(data.rate),
+              premium: data.premium,
+            });
+            if (errors.length) await handleErrors(errors);
+            eventsEmitted++;
+          }
+        }
+
+        // Position opened
+        if (eventBus.has('position_opened')) {
+          for (const [coin, pos] of snapshot.positions) {
+            if (!previousSnapshot.positions.has(coin)) {
+              const errors = await eventBus.emit('position_opened', {
+                coin,
+                side: pos.size > 0 ? 'long' : 'short',
+                size: Math.abs(pos.size),
+                entryPrice: pos.entryPrice,
+              });
+              if (errors.length) await handleErrors(errors);
+              eventsEmitted++;
+            }
+          }
+        }
+
+        // Position closed
+        if (eventBus.has('position_closed')) {
+          for (const [coin, prevPos] of previousSnapshot.positions) {
+            if (!snapshot.positions.has(coin)) {
+              const errors = await eventBus.emit('position_closed', {
+                coin,
+                previousSize: prevPos.size,
+                entryPrice: prevPos.entryPrice,
+              });
+              if (errors.length) await handleErrors(errors);
+              eventsEmitted++;
+            }
+          }
+        }
+
+        // Position size changed
+        if (eventBus.has('position_changed')) {
+          for (const [coin, pos] of snapshot.positions) {
+            const prevPos = previousSnapshot.positions.get(coin);
+            if (prevPos && pos.size !== prevPos.size) {
+              const errors = await eventBus.emit('position_changed', {
+                coin,
+                oldSize: prevPos.size,
+                newSize: pos.size,
+                entryPrice: pos.entryPrice,
+              });
+              if (errors.length) await handleErrors(errors);
+              eventsEmitted++;
+            }
+          }
+        }
+
+        // PnL threshold (5% of position value)
+        if (eventBus.has('pnl_threshold')) {
+          for (const [coin, pos] of snapshot.positions) {
+            const prevPos = previousSnapshot.positions.get(coin);
+            if (!prevPos || pos.positionValue === 0) continue;
+            const pnlChange = Math.abs(pos.unrealizedPnl - prevPos.unrealizedPnl);
+            const changePct = (pnlChange / pos.positionValue) * 100;
+            if (changePct >= 5) {
+              const errors = await eventBus.emit('pnl_threshold', {
+                coin,
+                unrealizedPnl: pos.unrealizedPnl,
+                changePct,
+                positionValue: pos.positionValue,
+              });
+              if (errors.length) await handleErrors(errors);
+              eventsEmitted++;
+            }
+          }
+        }
+
+        // Margin warning (80%)
+        if (eventBus.has('margin_warning') && snapshot.marginUsedPct >= 80) {
+          const prevPct = previousSnapshot.marginUsedPct;
+          if (prevPct < 80 || snapshot.marginUsedPct - prevPct >= 5) {
+            const errors = await eventBus.emit('margin_warning', {
+              marginUsedPct: snapshot.marginUsedPct,
+              equity: snapshot.equity,
+              marginUsed: snapshot.marginUsed,
+            });
+            if (errors.length) await handleErrors(errors);
+            eventsEmitted++;
+          }
+        }
+
+        // Order filled — compare open order IDs
+        // (Skipped for MVP — requires tracking open orders per poll, will add when needed)
+      }
+
+      // Run scheduled tasks
+      for (const task of scheduledTasks) {
+        if (now - task.lastRun >= task.intervalMs) {
+          try {
+            await task.handler();
+          } catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            log.error(`Scheduled task error: ${error.message}`);
+            await handleErrors([error]);
+          }
+          task.lastRun = now;
+        }
+      }
+
+      previousSnapshot = snapshot;
+    } catch (err) {
+      log.error(`Poll error: ${err instanceof Error ? err.message : String(err)}`);
+    } finally {
+      isPolling = false;
+    }
+  }
+
+  // Start polling
+  log.info(`Started (poll every ${pollIntervalMs / 1000}s, dry=${dryRun})`);
+  const timer = setInterval(poll, pollIntervalMs);
+
+  // Initial poll to seed state
+  await poll();
+
+  // Stop function
+  async function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+
+    for (const hook of stopHooks) {
+      try { await hook(); } catch (err) {
+        log.error(`onStop hook error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    eventBus.removeAll();
+    registry.delete(id);
+    log.info(`Stopped (${pollCount} polls, ${eventsEmitted} events)`);
+  }
+
+  const entry: RunningAutomation = {
+    id,
+    scriptPath,
+    startedAt: new Date(),
+    get pollCount() { return pollCount; },
+    get eventsEmitted() { return eventsEmitted; },
+    dryRun,
+    stop,
+  };
+
+  registry.set(id, entry);
+  return entry;
+}

package/scripts/auto/types.ts

@@ -0,0 +1,138 @@
+// Trading Automation Harness — Type definitions
+// The API contract that automation scripts code against
+
+import type { HyperliquidClient } from '../core/client.js';
+
+// ── Factory function ────────────────────────────────────────────────
+
+/** What an automation .ts file exports */
+export type AutomationFactory = (api: AutomationAPI) => void | Promise<void>;
+
+// ── Event system ────────────────────────────────────────────────────
+
+export type AutomationEventType =
+  | 'tick'
+  | 'price_change'
+  | 'funding_update'
+  | 'position_opened'
+  | 'position_closed'
+  | 'position_changed'
+  | 'pnl_threshold'
+  | 'margin_warning'
+  | 'order_filled';
+
+export interface AutomationEventPayloads {
+  tick: { timestamp: number; pollCount: number };
+  price_change: { coin: string; oldPrice: number; newPrice: number; changePct: number };
+  funding_update: { coin: string; fundingRate: number; annualized: number; premium: number };
+  position_opened: { coin: string; side: 'long' | 'short'; size: number; entryPrice: number };
+  position_closed: { coin: string; previousSize: number; entryPrice: number };
+  position_changed: { coin: string; oldSize: number; newSize: number; entryPrice: number };
+  pnl_threshold: { coin: string; unrealizedPnl: number; changePct: number; positionValue: number };
+  margin_warning: { marginUsedPct: number; equity: number; marginUsed: number };
+  order_filled: { coin: string; oid: number; side: 'buy' | 'sell'; size: number; price: number };
+}
+
+export type AutomationEventHandler<E extends AutomationEventType> =
+  (payload: AutomationEventPayloads[E]) => void | Promise<void>;
+
+// ── State & logging ─────────────────────────────────────────────────
+
+export interface AutomationState {
+  get<T = unknown>(key: string, defaultValue?: T): T | undefined;
+  set<T = unknown>(key: string, value: T): void;
+  delete(key: string): void;
+  clear(): void;
+}
+
+export interface AutomationLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  debug(message: string): void;
+}
+
+// ── Core API ────────────────────────────────────────────────────────
+
+export interface AutomationAPI {
+  /** Full Hyperliquid client (42+ methods) */
+  client: HyperliquidClient;
+
+  /** Convenience utilities from core */
+  utils: {
+    roundPrice: (price: number, szDecimals: number, isSpot?: boolean) => string;
+    roundSize: (size: number, szDecimals: number) => string;
+    sleep: (ms: number) => Promise<void>;
+    normalizeCoin: (coin: string) => string;
+    formatUsd: (amount: number | string) => string;
+    formatPercent: (value: number | string, decimals?: number) => string;
+    annualizeFundingRate: (hourlyRate: number | string) => number;
+  };
+
+  /** Subscribe to a market/account event */
+  on<E extends AutomationEventType>(event: E, handler: AutomationEventHandler<E>): void;
+
+  /** Run a handler on a recurring interval (ms). Aligned to the poll loop. */
+  every(intervalMs: number, handler: () => void | Promise<void>): void;
+
+  /** Called after all handlers are registered and polling begins */
+  onStart(handler: () => void | Promise<void>): void;
+
+  /** Called when automation is stopping (SIGINT, manual stop). Use for cleanup. */
+  onStop(handler: () => void | Promise<void>): void;
+
+  /** Called when a handler throws. The error is already logged — use this for recovery logic. */
+  onError(handler: (error: Error) => void | Promise<void>): void;
+
+  /** Persisted key-value state (~/.openbroker/state/<id>.json) */
+  state: AutomationState;
+
+  /** Structured logger */
+  log: AutomationLogger;
+
+  /** Unique automation ID (derived from filename or --id flag) */
+  id: string;
+
+  /** True if running in --dry mode (write methods are intercepted) */
+  dryRun: boolean;
+}
+
+// ── Runtime internals ───────────────────────────────────────────────
+
+export interface AutomationSnapshot {
+  prices: Map<string, number>;
+  positions: Map<string, PositionSnapshot>;
+  openOrderIds: Set<number>;
+  equity: number;
+  marginUsed: number;
+  marginUsedPct: number;
+  fundingRates: Map<string, { rate: number; premium: number }>;
+  timestamp: number;
+}
+
+export interface PositionSnapshot {
+  coin: string;
+  size: number;
+  entryPrice: number;
+  positionValue: number;
+  unrealizedPnl: number;
+  liquidationPx: number | null;
+  leverage: number;
+  marginUsed: number;
+}
+
+export interface ScheduledTask {
+  intervalMs: number;
+  handler: () => void | Promise<void>;
+  lastRun: number;
+}
+
+export interface RunningAutomation {
+  id: string;
+  scriptPath: string;
+  startedAt: Date;
+  pollCount: number;
+  eventsEmitted: number;
+  dryRun: boolean;
+  stop: () => Promise<void>;
+}

package/scripts/plugin/tools.ts

@@ -1299,5 +1299,92 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         return json(watcher.getStatus());
       },
     },
+
+    // ── Automation Tools ──────────────────────────────────────────
+
+    {
+      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.',
+      parameters: {
+        type: 'object',
+        properties: {
+          script: { type: 'string', description: 'Script name (from ~/.openbroker/automations/) or absolute path' },
+          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 { startAutomation } = await import('../auto/runtime.js');
+
+          const scriptPath = resolveScriptPath(String(params.script));
+          const automation = await startAutomation({
+            scriptPath,
+            id: params.id ? String(params.id) : undefined,
+            dryRun: params.dry === true,
+            pollIntervalMs: params.poll ? Number(params.poll) : 10_000,
+          });
+
+          return json({
+            status: 'started',
+            id: automation.id,
+            scriptPath: automation.scriptPath,
+            dryRun: automation.dryRun,
+          });
+        } catch (err) {
+          return error(err instanceof Error ? err.message : String(err));
+        }
+      },
+    },
+
+    {
+      name: 'ob_auto_stop',
+      description: 'Stop a running trading automation by ID',
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Automation ID to stop' },
+        },
+        required: ['id'],
+      },
+      async execute(_id, params) {
+        try {
+          const { getAutomation } = await import('../auto/runtime.js');
+          const automation = getAutomation(String(params.id));
+          if (!automation) {
+            return error(`No running automation with ID "${params.id}"`);
+          }
+          await automation.stop();
+          return json({ status: 'stopped', id: params.id });
+        } catch (err) {
+          return error(err instanceof Error ? err.message : String(err));
+        }
+      },
+    },
+
+    {
+      name: 'ob_auto_list',
+      description: 'List available automation scripts and running automations',
+      parameters: { type: 'object', properties: {} },
+      async execute() {
+        const { listAutomations } = await import('../auto/loader.js');
+        const { getRunningAutomations } = await import('../auto/runtime.js');
+
+        const available = listAutomations();
+        const running = getRunningAutomations().map(a => ({
+          id: a.id,
+          scriptPath: a.scriptPath,
+          uptime: Math.round((Date.now() - a.startedAt.getTime()) / 1000),
+          pollCount: a.pollCount,
+          eventsEmitted: a.eventsEmitted,
+          dryRun: a.dryRun,
+        }));
+
+        return json({ available, running });
+      },
+    },
   ];
 }