openbroker 1.0.67 → 1.0.69

package/SKILL.md

@@ -4,7 +4,7 @@ description: Hyperliquid trading plugin with background position monitoring and
 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.67", "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)"}]}}
+metadata: {"author": "monemetrics", "version": "1.0.69", "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:*)
 ---
 
@@ -234,7 +234,6 @@ All trading commands support HIP-3 assets using `dex:COIN` syntax:
 openbroker buy --coin xyz:CL --size 1              # Buy crude oil on xyz dex
 openbroker sell --coin xyz:BRENTOIL --size 1        # Sell brent oil
 openbroker limit --coin xyz:GOLD --side buy --size 0.1 --price 2500
-openbroker funding-arb --coin xyz:CL --size 5000    # Funding arb on HIP-3
 ```
 
 ### Market Orders (Quick)
@@ -325,53 +324,6 @@ openbroker chase --coin ETH --side buy --size 0.5 --timeout 300
 openbroker chase --coin SOL --side buy --size 10 --offset 2 --timeout 60
 ```
 
-## Trading Strategies
-
-### Funding Arbitrage
-```bash
-# Collect funding on ETH if rate > 25% annualized
-openbroker funding-arb --coin ETH --size 5000 --min-funding 25
-
-# Run for 24 hours, check every 30 minutes
-openbroker funding-arb --coin BTC --size 10000 --duration 24 --check 30 --dry
-```
-
-### Grid Trading
-```bash
-# ETH grid from $3000-$4000 with 10 levels, 0.1 ETH per level
-openbroker grid --coin ETH --lower 3000 --upper 4000 --grids 10 --size 0.1
-
-# Accumulation grid (buys only)
-openbroker grid --coin BTC --lower 90000 --upper 100000 --grids 5 --size 0.01 --mode long
-```
-
-### DCA (Dollar Cost Averaging)
-```bash
-# Buy $100 of ETH every hour for 24 hours
-openbroker dca --coin ETH --amount 100 --interval 1h --count 24
-
-# Invest $5000 in BTC over 30 days with daily purchases
-openbroker dca --coin BTC --total 5000 --interval 1d --count 30
-```
-
-### Market Making Spread
-```bash
-# Market make ETH with 0.1 size, 10bps spread
-openbroker mm-spread --coin ETH --size 0.1 --spread 10
-
-# Tighter spread with position limit
-openbroker mm-spread --coin BTC --size 0.01 --spread 5 --max-position 0.1
-```
-
-### Maker-Only MM (ALO orders)
-```bash
-# Market make using ALO (post-only) orders - guarantees maker rebates
-openbroker mm-maker --coin HYPE --size 1 --offset 1
-
-# Wider offset for volatile assets
-openbroker mm-maker --coin ETH --size 0.1 --offset 2 --max-position 0.5
-```
-
 ## Order Types
 
 ### Limit Orders vs Trigger Orders
@@ -495,7 +447,24 @@ Without hooks, the watcher still runs and tracks state (accessible via `ob_watch
 
 ## 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.
+Automations let you write custom event-driven trading logic as TypeScript scripts. Write exactly the logic you need and OpenBroker handles the polling, event detection, and SDK access.
+
+### IMPORTANT: Bundled Examples Are References, Not Ready-Made Strategies
+
+OpenBroker ships bundled automation examples (`dca`, `grid`, `funding-arb`, `mm-spread`, `mm-maker`) that demonstrate common patterns. **These examples are meant to be read and learned from — not run directly as production strategies.** When the user asks for a strategy (e.g. "run a DCA on HYPE"), you should:
+
+1. Read the relevant bundled example source code to understand the automation API patterns
+2. Write a **custom automation** tailored to the user's specific requirements (coin, size, thresholds, risk parameters, TP/SL logic, etc.)
+3. Save it to `~/.openbroker/automations/` and run it with `openbroker auto run`
+
+Do NOT simply run `openbroker auto run --example dca --set coin=HYPE`. The examples use generic defaults and lack the nuanced risk management, position sizing, and TP/SL logic that a real strategy needs. Always write a purpose-built automation.
+
+To view bundled examples and their config schemas:
+```bash
+openbroker auto examples    # List examples with config fields
+```
+
+Available examples: `dca`, `grid`, `funding-arb`, `mm-spread`, `mm-maker`
 
 ### How Automations Work
 
@@ -763,15 +732,86 @@ api.on('margin_warning', async ({ marginUsedPct, equity }) => {
 
 ### Client Methods Available
 
-The `api.client` object exposes the full Hyperliquid SDK:
+The `api.client` object exposes the full `HyperliquidClient`. All `coin` params accept HIP-3 prefixed tickers (e.g. `xyz:CL`). Optional `user` params default to the configured wallet address.
+
+#### Trading
+
+| Method | Description |
+|--------|-------------|
+| `marketOrder(coin, isBuy, size, slippageBps?, leverage?)` | Market order via IOC limit at mid ± slippage. Returns `OrderResponse` |
+| `limitOrder(coin, isBuy, size, price, tif?, reduceOnly?, leverage?)` | Limit order. `tif`: `'Gtc'` (default), `'Ioc'`, `'Alo'`. Returns `OrderResponse` |
+| `triggerOrder(coin, isBuy, size, triggerPrice, limitPrice, tpsl, reduceOnly?, leverage?)` | Trigger (conditional) order. `tpsl`: `'tp'` or `'sl'`. Activates when price hits `triggerPrice`, then fills as limit at `limitPrice`. Returns `OrderResponse` |
+| `stopLoss(coin, isBuy, size, triggerPrice, slippageBps?)` | Stop loss shortcut. Sets limit price with slippage buffer (default 100 bps / 1%) to ensure fill. `reduceOnly` is always true. Returns `OrderResponse` |
+| `takeProfit(coin, isBuy, size, triggerPrice)` | Take profit shortcut. Limit price = trigger price (favorable direction). `reduceOnly` is always true. Returns `OrderResponse` |
+| `cancel(coin, oid)` | Cancel a single order by numeric OID. Returns `CancelResponse` |
+| `cancelAll(coin?)` | Cancel all open orders. If `coin` is provided, only cancels orders for that asset. Returns `CancelResponse[]` |
+| `order(coin, isBuy, size, price, orderType, reduceOnly?, includeBuilder?, leverage?)` | Low-level order placement. `orderType`: `{ limit: { tif: 'Gtc' | 'Ioc' | 'Alo' } }`. Automatically injects builder fee, rounds price/size, and handles HIP-3 margin setup. Returns `OrderResponse` |
+
+#### Market Data
+
+| Method | Returns |
+|--------|---------|
+| `getAllMids()` | `Record<string, string>` — mid prices for all assets (main + HIP-3). Key = coin name, value = price string |
+| `getMetaAndAssetCtxs()` | `MetaAndAssetCtxs` — market metadata (universe of assets with `szDecimals`, `maxLeverage`) and asset contexts (funding, open interest, volume, mark/oracle prices) |
+| `getL2Book(coin)` | `{ bids, asks, bestBid, bestAsk, midPrice, spread, spreadBps }` — L2 order book with computed spread |
+| `getRecentTrades(coin)` | `Array<{ coin, side, px, sz, time, hash, tid }>` — recent trade tape. `side`: `'B'` (buy) or `'A'` (sell) |
+| `getCandleSnapshot(coin, interval, startTime, endTime?)` | `Array<{ t, T, s, i, o, c, h, l, v, n }>` — OHLCV candles. `interval`: `'1m'`, `'5m'`, `'15m'`, `'1h'`, `'4h'`, `'1d'`. Times are Unix ms |
+| `getFundingHistory(coin, startTime, endTime?)` | `Array<{ coin, fundingRate, premium, time }>` — historical hourly funding rates |
+| `getPredictedFundings()` | `Array<[coin, Array<[venue, { fundingRate, nextFundingTime }]>]>` — predicted funding rates across all venues |
+| `getPerpDexs()` | `Array<{ name, fullName, deployer } | null>` — list of perp DEXs. Index 0 is `null` (main), rest are HIP-3 |
+| `getAllPerpMetas()` | `Array<{ dexName, meta, assetCtxs }>` — metadata + contexts for every perp DEX (main + all HIP-3) |
+| `getSpotMeta()` | `{ tokens, universe }` — spot market metadata (token info, trading pairs) |
+| `getSpotMetaAndAssetCtxs()` | `{ meta, assetCtxs }` — spot metadata + price/volume contexts |
+| `getTokenDetails(tokenId)` | Token details: supply, deployer, prices. Returns `null` if not found |
+
+#### Account
+
+| Method | Returns |
+|--------|---------|
+| `getUserStateAll(user?)` | `ClearinghouseState` — full account state across all dexes: `marginSummary` (accountValue, totalMarginUsed, withdrawable), `crossMarginSummary`, and `assetPositions[]` (each with `position.coin`, `.szi`, `.entryPx`, `.unrealizedPnl`, `.positionValue`, `.leverage`, `.marginUsed`, `.liquidationPx`) |
+| `getUserState(user?, dex?)` | `ClearinghouseState` — account state for a single dex (omit `dex` for main perps) |
+| `getOpenOrders(user?)` | `OpenOrder[]` — all open orders across all dexes. Each: `{ coin, side, limitPx, sz, oid, timestamp, orderType }` |
+| `getUserFills(user?, aggregateByTime?)` | `Array<{ coin, px, sz, side, time, closedPnl, fee, oid, tid, crossed, builderFee }>` — trade fill history. `side`: `'B'` (buy) or `'A'` (sell) |
+| `getHistoricalOrders(user?)` | `Array<{ order: { coin, side, limitPx, sz, origSz, oid, timestamp, orderType, tif, triggerCondition, triggerPx, isTrigger, isPositionTpsl, reduceOnly }, status, statusTimestamp }>` — all orders (filled, cancelled, etc.) |
+| `getOrderStatus(oid, user?)` | `{ status, order? }` — status of a specific order by numeric OID or string CLOID |
+| `getUserFunding(user?, startTime?, endTime?)` | `Array<{ time, hash, delta: { coin, usdc, szi, fundingRate } }>` — funding payments received/paid |
+| `getUserFees(user?)` | `{ dailyUserVlm, feeSchedule, userCrossRate, userAddRate, activeReferralDiscount, activeStakingDiscount }` — fee tier, rates, and volume |
+| `getUserRateLimit(user?)` | `{ cumVlm, nRequestsUsed, nRequestsCap, nRequestsSurplus }` — API rate limit status |
+| `getSpotBalances(user?)` | `{ balances: Array<{ coin, token, hold, total, entryNtl }> }` — spot token balances |
+| `getSubAccounts(user?)` | `Array<{ subAccountUser, name }>` — sub-accounts for a master wallet |
+| `getAccountMode(user?)` | `string` — account abstraction mode: `'standard'`, `'unified'`, `'portfolio'`, or `'dexAbstraction'` |
+| `isUnifiedAccount(user?)` | `boolean` — `true` if unified or portfolio margin (shared USDC across dexes) |
+
+#### Leverage & Config
+
+| Method | Description |
+|--------|-------------|
+| `updateLeverage(coin, leverage, isCross?)` | Set leverage. `isCross` defaults to `true` (cross margin). HIP-3 assets are forced to isolated and clamped to their max leverage |
+| `approveBuilderFee(maxFeeRate?, builder?)` | Approve builder fee (must be called from main wallet, not API wallet). Default rate: `'0.1%'` |
+| `getMaxBuilderFee(user?, builder?)` | Check approved builder fee. Returns fee string (e.g. `'0.01%'`) or `null` if not approved |
+
+#### Utility Properties
 
-**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()`
+| Property / Method | Description |
+|-------------------|-------------|
+| `getAssetIndex(coin)` | Get numeric asset index for a coin (used internally for order wire) |
+| `getSzDecimals(coin)` | Get size decimal precision for a coin |
+| `isHip3(coin)` | Check if a coin is a HIP-3 asset |
+| `getCoinDex(coin)` | Get dex name for a coin (`null` for main perps) |
+| `getAllAssetNames()` | Get all known asset names (main + HIP-3) |
+| `getHip3AssetNames()` | Get only HIP-3 asset names |
+| `invalidateMetaCache()` | Force refresh of market metadata on next call |
 
-**Account:** `getUserStateAll()`, `getOpenOrders()`, `getUserFills()`, `getUserFunding()`, `getHistoricalOrders()`, `getUserFees()`, `getUserRateLimit()`, `getSpotBalances()`
+#### Utility Functions (`api.utils`)
 
-**Leverage:** `updateLeverage(coin, leverage, isIsolated?)`
+| Function | Description |
+|----------|-------------|
+| `roundPrice(price, szDecimals, isSpot?)` | Round price to 5 significant figures (max 6 decimals perp, 8 spot) |
+| `roundSize(size, szDecimals)` | Round size to asset-specific decimal precision |
+| `sleep(ms)` | Promise-based delay |
+| `normalizeCoin(coin)` | Normalize coin name (uppercase, trim whitespace) |
+| `formatUsd(amount)` | Format number as USD string (e.g. `$1,234.56`) |
+| `annualizeFundingRate(hourlyRate)` | Convert hourly funding rate to annualized percentage |
 
 ### Example: Price Breakout
 
@@ -897,14 +937,17 @@ export default function(api) {
 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 run --example dca --set coin=HYPE --set amount=50 --dry  # Run bundled example
+openbroker auto examples                    # List bundled examples with config
 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_run` — `{ "example": "dca", "config": { "coin": "HYPE", "amount": 50 }, "dry": true }` — run a bundled example
 - `ob_auto_stop` — `{ "id": "funding-scalp" }` — stop a running automation
-- `ob_auto_list` — `{}` — list available and running automations
+- `ob_auto_list` — `{}` — list available automations, bundled examples with config schemas, and running automations
 
 **Options:**
 | Flag | Description | Default |
@@ -913,6 +956,8 @@ openbroker auto status                      # Show running automations
 | `--verbose` | Show debug output | false |
 | `--id <name>` | Custom automation ID | filename |
 | `--poll <ms>` | Poll interval in milliseconds | 10000 |
+| `--example <name>` | Run a bundled example automation | - |
+| `--set key=value` | Set config values (repeatable) | - |
 
 **Guidelines for agents writing automations:**
 

package/bin/cli.ts

@@ -46,13 +46,6 @@ const commands: Record<string, { script: string; description: string }> = {
   'bracket': { script: 'operations/bracket.ts', description: 'Bracket order (entry + TP + SL)' },
   'chase': { script: 'operations/chase.ts', description: 'Chase order with ALO' },
 
-  // Strategies
-  'funding-arb': { script: 'strategies/funding-arb.ts', description: 'Funding arbitrage strategy' },
-  'grid': { script: 'strategies/grid.ts', description: 'Grid trading strategy' },
-  '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' },
 };
@@ -99,15 +92,10 @@ Advanced Execution:
   bracket              Entry with TP and SL
   chase                Chase price with ALO orders
 
-Strategies:
-  funding-arb          Funding rate arbitrage
-  grid                 Grid trading
-  dca                  Dollar cost averaging
-  mm-spread            Market making (spread-based)
-  mm-maker             Market making (ALO orders)
-
 Automations:
   auto run <script>    Run a custom trading automation
+  auto run --example <name> [--set key=value]  Run a bundled example
+  auto examples        List bundled examples (dca, grid, funding-arb, mm-spread, mm-maker)
   auto list            List available automations
   auto status          Show running automations
 

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.67",
+  "version": "1.0.69",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -39,11 +39,6 @@
     "bracket": "tsx scripts/operations/bracket.ts",
     "chase": "tsx scripts/operations/chase.ts",
     "funding-scan": "tsx scripts/info/funding-scan.ts",
-    "funding-arb": "tsx scripts/strategies/funding-arb.ts",
-    "grid": "tsx scripts/strategies/grid.ts",
-    "dca": "tsx scripts/strategies/dca.ts",
-    "mm-spread": "tsx scripts/strategies/mm-spread.ts",
-    "mm-maker": "tsx scripts/strategies/mm-maker.ts",
     "prepublishOnly": "npm run test:cli",
     "test:cli": "node --import tsx bin/cli.ts --help"
   },
@@ -62,11 +57,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aurracloud/openbroker.git"
+    "url": "git+https://github.com/aurracloud/open-broker.git"
   },
-  "homepage": "https://github.com/aurracloud/openbroker#readme",
+  "homepage": "https://github.com/aurracloud/open-broker#readme",
   "bugs": {
-    "url": "https://github.com/aurracloud/openbroker/issues"
+    "url": "https://github.com/aurracloud/open-broker/issues"
   },
   "author": "aurracloud",
   "keywords": [

package/scripts/auto/cli.ts

@@ -1,7 +1,7 @@
 // CLI entry point for `openbroker auto` commands
 
 import { parseArgs } from '../core/utils.js';
-import { resolveScriptPath, listAutomations, ensureAutomationsDir } from './loader.js';
+import { resolveScriptPath, resolveExamplePath, listAutomations, listExamples, loadExampleConfigs, ensureAutomationsDir } from './loader.js';
 import { startAutomation, getRunningAutomations, getRegisteredAutomations } from './runtime.js';
 import { unregisterAutomation, cleanRegistry } from './registry.js';
 
@@ -11,12 +11,16 @@ OpenBroker Automations — event-driven trading scripts
 
 Usage:
   openbroker auto run <script> [options]    Run an automation script
+  openbroker auto run --example <name>      Run a bundled example automation
+  openbroker auto examples                  List bundled example automations
   openbroker auto stop <id>                 Unregister an automation (won't restart)
   openbroker auto list                      List available automations
   openbroker auto status                    Show running automations
   openbroker auto clean                     Remove stale entries from registry
 
 Options (for run):
+  --example <name>   Run a bundled example (dca, grid, funding-arb, mm-spread, mm-maker)
+  --set key=value    Set config values (repeatable, auto-parses numbers/booleans)
   --dry              Intercept write methods (no real trades)
   --verbose          Show debug output
   --id <name>        Custom automation ID (default: filename)
@@ -25,6 +29,7 @@ Options (for run):
 Scripts are loaded from:
   1. Absolute or relative path
   2. ~/.openbroker/automations/<name>.ts
+  3. Bundled examples (via --example)
 
 Writing an automation:
   export default function(api) {
@@ -37,21 +42,66 @@ 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
+  openbroker auto run --example dca --set coin=BTC --set amount=50 --dry
+  openbroker auto run --example grid --set coin=ETH --set lower=3000 --set upper=4000
+  openbroker auto run my-strategy --dry
+  openbroker auto examples
 `);
 }
 
-async function runCommand(args: Record<string, string | boolean>, positional: string[]) {
+/** Parse --set key=value flags from raw args, return parsed config object */
+function parseSetFlags(rawArgs: string[]): Record<string, unknown> {
+  const config: Record<string, unknown> = {};
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--set' && i + 1 < rawArgs.length) {
+      const pair = rawArgs[i + 1];
+      const eqIdx = pair.indexOf('=');
+      if (eqIdx === -1) {
+        console.error(`Error: --set requires key=value format, got: ${pair}`);
+        process.exit(1);
+      }
+      const key = pair.slice(0, eqIdx);
+      const raw = pair.slice(eqIdx + 1);
+
+      // Auto-parse numbers and booleans
+      if (raw === 'true') config[key] = true;
+      else if (raw === 'false') config[key] = false;
+      else if (raw !== '' && !isNaN(Number(raw))) config[key] = Number(raw);
+      else config[key] = raw;
+
+      i++; // skip the value
+    }
+  }
+
+  return config;
+}
+
+/** Strip --set key=value pairs from raw args so parseArgs doesn't see them */
+function stripSetFlags(rawArgs: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--set' && i + 1 < rawArgs.length) {
+      i++; // skip --set and its value
+    } else {
+      result.push(rawArgs[i]);
+    }
+  }
+  return result;
+}
+
+async function runCommand(args: Record<string, string | boolean>, positional: string[], initialState: Record<string, unknown>) {
+  const exampleName = args.example ? String(args.example) : undefined;
   const scriptName = positional[0];
-  if (!scriptName) {
-    console.error('Error: script name or path required');
+
+  if (!scriptName && !exampleName) {
+    console.error('Error: script name or path required (or use --example <name>)');
     console.log('Usage: openbroker auto run <script> [--dry] [--verbose]');
+    console.log('       openbroker auto run --example <name> [--set key=value] [--dry]');
     process.exit(1);
   }
 
-  const scriptPath = resolveScriptPath(scriptName);
+  const scriptPath = exampleName ? resolveExamplePath(exampleName) : resolveScriptPath(scriptName!);
   const dryRun = args.dry === true;
   const verbose = args.verbose === true;
   const pollIntervalMs = args.poll ? parseInt(String(args.poll), 10) : 10_000;
@@ -68,6 +118,7 @@ async function runCommand(args: Record<string, string | boolean>, positional: st
     dryRun,
     verbose,
     pollIntervalMs,
+    initialState: Object.keys(initialState).length > 0 ? initialState : undefined,
   });
 
   // Graceful shutdown on SIGINT/SIGTERM
@@ -84,22 +135,58 @@ async function runCommand(args: Record<string, string | boolean>, positional: st
   await new Promise(() => {});
 }
 
+async function examplesCommand() {
+  const configs = await loadExampleConfigs();
+  const names = Object.keys(configs);
+
+  if (names.length === 0) {
+    console.log('No bundled examples found.');
+    return;
+  }
+
+  console.log('Bundled example automations:\n');
+  for (const name of names) {
+    const cfg = configs[name];
+    console.log(`  ${name}`);
+    console.log(`    ${cfg.description}\n`);
+
+    console.log(`    Config (--set key=value):`);
+    for (const [key, field] of Object.entries(cfg.fields)) {
+      const def = JSON.stringify(field.default);
+      console.log(`      ${key.padEnd(14)} ${field.type.padEnd(8)} ${field.description} (default: ${def})`);
+    }
+    console.log('');
+  }
+
+  console.log(`Run with: openbroker auto run --example <name> [--set key=value] [--dry]`);
+  console.log('Copy to ~/.openbroker/automations/ to customize.');
+}
+
 function listCommand() {
   ensureAutomationsDir();
   const automations = listAutomations();
+  const examples = listExamples();
 
-  if (automations.length === 0) {
+  if (automations.length === 0 && examples.length === 0) {
     console.log('No automations found in ~/.openbroker/automations/');
     console.log('\nCreate a .ts file there with:');
     console.log('  export default function(api) { ... }');
+    console.log('\nOr run a bundled example: openbroker auto examples');
     return;
   }
 
-  console.log('Available automations:\n');
-  for (const a of automations) {
-    console.log(`  ${a.name.padEnd(30)} ${a.path}`);
+  if (automations.length > 0) {
+    console.log('User automations (~/.openbroker/automations/):\n');
+    for (const a of automations) {
+      console.log(`  ${a.name.padEnd(30)} ${a.path}`);
+    }
+    console.log(`\nRun with: openbroker auto run <name>`);
+  }
+
+  if (examples.length > 0) {
+    if (automations.length > 0) console.log('');
+    console.log(`${examples.length} bundled examples available — run: openbroker auto examples`);
   }
-  console.log(`\nRun with: openbroker auto run <name>`);
 }
 
 function statusCommand() {
@@ -192,19 +279,23 @@ async function main() {
   const subcommand = rawArgs[0];
   const restArgs = rawArgs.slice(1);
 
+  // Parse --set flags before stripping them
+  const initialState = parseSetFlags(restArgs);
+  const cleanedArgs = stripSetFlags(restArgs);
+
   // 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]);
+  for (let i = 0; i < cleanedArgs.length; i++) {
+    if (cleanedArgs[i].startsWith('--')) {
+      flagArgs.push(cleanedArgs[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]);
+      if (i + 1 < cleanedArgs.length && !cleanedArgs[i + 1].startsWith('--')) {
+        flagArgs.push(cleanedArgs[i + 1]);
         i++;
       }
     } else {
-      positional.push(restArgs[i]);
+      positional.push(cleanedArgs[i]);
     }
   }
 
@@ -212,7 +303,7 @@ async function main() {
 
   switch (subcommand) {
     case 'run':
-      await runCommand(args, positional);
+      await runCommand(args, positional, initialState);
       break;
     case 'stop':
       stopCommand(positional);
@@ -220,6 +311,9 @@ async function main() {
     case 'list':
       listCommand();
       break;
+    case 'examples':
+      await examplesCommand();
+      break;
     case 'status':
       statusCommand();
       break;

package/scripts/auto/examples/dca.ts

@@ -0,0 +1,72 @@
+// DCA (Dollar Cost Averaging) — Buy fixed USD amounts at regular intervals
+
+import type { AutomationAPI, AutomationConfig } from '../types.js';
+
+export const config: AutomationConfig = {
+  description: 'Dollar cost averaging — buy fixed USD amounts at regular intervals',
+  fields: {
+    coin:     { type: 'string', description: 'Asset to accumulate', default: 'HYPE' },
+    amount:   { type: 'number', description: 'USD per purchase', default: 100 },
+    interval: { type: 'number', description: 'Milliseconds between buys (3600000 = 1h)', default: 3_600_000 },
+    count:    { type: 'number', description: 'Total number of purchases', default: 24 },
+  },
+};
+
+export default function dca(api: AutomationAPI) {
+  const COIN = api.state.get<string>('coin', 'HYPE')!;
+  const AMOUNT_USD = api.state.get<number>('amount', 100)!;
+  const INTERVAL_MS = api.state.get<number>('interval', 3_600_000)!;
+  const MAX_PURCHASES = api.state.get<number>('count', 24)!;
+
+  let purchased = api.state.get<number>('purchased', 0)!;
+  let totalSpent = api.state.get<number>('totalSpent', 0)!;
+  let totalAcquired = api.state.get<number>('totalAcquired', 0)!;
+
+  api.onStart(() => {
+    api.log.info(`DCA: ${MAX_PURCHASES} buys of $${AMOUNT_USD} ${COIN} every ${INTERVAL_MS / 60000}m`);
+    api.log.info(`Progress: ${purchased}/${MAX_PURCHASES} completed`);
+  });
+
+  api.every(INTERVAL_MS, async () => {
+    if (purchased >= MAX_PURCHASES) {
+      api.log.info(`DCA complete: ${purchased} purchases, $${totalSpent.toFixed(2)} spent, ${totalAcquired.toFixed(6)} ${COIN} acquired`);
+      return;
+    }
+
+    const mids = await api.client.getAllMids();
+    const price = parseFloat(mids[COIN]);
+    if (!price) {
+      api.log.warn(`No price for ${COIN}, skipping`);
+      return;
+    }
+
+    const size = AMOUNT_USD / price;
+    api.log.info(`[${purchased + 1}/${MAX_PURCHASES}] Buying ~$${AMOUNT_USD} of ${COIN} @ $${price.toFixed(2)}`);
+
+    const response = await api.client.marketOrder(COIN, true, size);
+    if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+      const status = response.response.data.statuses[0];
+      if (status?.filled) {
+        const filledSize = parseFloat(status.filled.totalSz);
+        const avgPx = parseFloat(status.filled.avgPx);
+        totalSpent += filledSize * avgPx;
+        totalAcquired += filledSize;
+        purchased++;
+
+        api.state.set('purchased', purchased);
+        api.state.set('totalSpent', totalSpent);
+        api.state.set('totalAcquired', totalAcquired);
+
+        const avgPrice = totalSpent / totalAcquired;
+        api.log.info(`Filled ${filledSize.toFixed(6)} @ $${avgPx.toFixed(2)} | Avg: $${avgPrice.toFixed(2)} | Total: ${totalAcquired.toFixed(6)} ${COIN}`);
+      } else if (status?.error) {
+        api.log.error(`Order failed: ${status.error}`);
+      }
+    }
+  });
+
+  api.onStop(() => {
+    const avgPrice = totalAcquired > 0 ? totalSpent / totalAcquired : 0;
+    api.log.info(`DCA stopped: ${purchased}/${MAX_PURCHASES} | Spent: $${totalSpent.toFixed(2)} | Acquired: ${totalAcquired.toFixed(6)} ${COIN} | Avg: $${avgPrice.toFixed(2)}`);
+  });
+}