openbroker 1.0.69 → 1.0.71

package/README.md

@@ -383,16 +383,19 @@ openbroker cancel --all --dry              # Preview what would be cancelled
 
 ### Advanced Execution
 
-#### `twap` — Time-Weighted Average Price
+#### `twap` — Native TWAP Order
 
-Split a large order into smaller slices executed at regular intervals to minimize market impact.
+Place a native Hyperliquid TWAP order. The exchange handles order slicing and execution timing server-side — returns immediately with a TWAP ID.
 
 ```bash
-# Buy 1 ETH over 1 hour (auto ~12 slices)
-openbroker twap --coin ETH --side buy --size 1 --duration 3600
+# Buy 1 ETH over 30 minutes
+openbroker twap --coin ETH --side buy --size 1 --duration 30
 
-# Sell 0.5 BTC over 30 min, 6 slices, randomized timing
-openbroker twap --coin BTC --side sell --size 0.5 --duration 1800 --intervals 6 --randomize 20
+# Sell 0.5 BTC over 2 hours without randomized timing
+openbroker twap --coin BTC --side sell --size 0.5 --duration 120 --randomize false
+
+# Preview order details
+openbroker twap --coin ETH --side buy --size 2 --duration 60 --dry
 ```
 
 | Flag | Description | Default |
@@ -400,14 +403,38 @@ openbroker twap --coin BTC --side sell --size 0.5 --duration 1800 --intervals 6
 | `--coin` | Asset to trade | **required** |
 | `--side` | `buy` or `sell` | **required** |
 | `--size` | Total order size in base asset | **required** |
-| `--duration` | Total execution time in seconds | **required** |
-| `--intervals` | Number of slices | 1 per 5 min |
-| `--randomize` | Randomize timing by ±X percent | `0` |
-| `--slippage` | Slippage per slice in bps | `50` |
-| `--dry` | Show execution plan without trading | — |
+| `--duration` | Duration in minutes (5–1440) | **required** |
+| `--randomize` | Randomize execution timing | `true` |
+| `--reduce-only` | Reduce-only order | `false` |
+| `--leverage` | Set leverage before placing | — |
+| `--dry` | Show order details without placing | — |
 | `--verbose` | Show debug output | — |
 
-Reports VWAP, actual slippage, fill rate, and total execution time.
+#### `twap-cancel` — Cancel TWAP Order
+
+Cancel a running native TWAP order by its TWAP ID.
+
+```bash
+openbroker twap-cancel --coin ETH --twap-id 77738308
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--coin` | Asset symbol | **required** |
+| `--twap-id` | TWAP order ID to cancel | **required** |
+
+#### `twap-status` — TWAP Order Status
+
+View TWAP order history and currently running TWAP orders.
+
+```bash
+openbroker twap-status              # All TWAP history
+openbroker twap-status --active     # Only running TWAPs
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--active` | Show only active/running TWAP orders | — |
 
 #### `scale` — Scale In/Out
 
@@ -724,7 +751,9 @@ When loaded, the plugin registers these agent tools:
 | Trading | `ob_trigger` | Trigger order (TP/SL) |
 | Trading | `ob_tpsl` | Set TP/SL on existing position |
 | Trading | `ob_cancel` | Cancel orders |
-| Advanced | `ob_twap` | TWAP execution |
+| Advanced | `ob_twap` | Native TWAP order (exchange-managed) |
+| Advanced | `ob_twap_cancel` | Cancel a running TWAP order |
+| Advanced | `ob_twap_status` | View TWAP order history/status |
 | Advanced | `ob_bracket` | Entry + TP + SL |
 | Advanced | `ob_chase` | Chase price with ALO orders |
 | Monitoring | `ob_watcher_status` | Background watcher state |

package/SKILL.md

@@ -4,8 +4,8 @@ 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.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:*)
+metadata: {"author": "monemetrics", "version": "1.0.71", "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_twap_cancel ob_twap_status ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI
@@ -73,7 +73,7 @@ If an `ob_*` plugin tool returns unexpected errors, empty results, or crashes, *
 **When to use CLI fallback:**
 - Plugin tool returns `null`, empty data, or throws an error
 - You need data the plugin tool doesn't expose (e.g., `--verbose` debug output)
-- Long-running operations (strategies, TWAP) — the CLI handles timeouts and progress better
+- Long-running operations (strategies) — the CLI handles timeouts and progress better
 
 Add `--dry` to any trading CLI command to preview without executing. Add `--json` to info commands for structured output.
 
@@ -288,13 +288,19 @@ openbroker cancel --oid 123456    # Cancel specific order
 
 ## Advanced Execution
 
-### TWAP (Time-Weighted Average Price)
+### TWAP (Native Exchange Order)
 ```bash
-# Execute 1 ETH buy over 1 hour (auto-calculates slices)
-openbroker twap --coin ETH --side buy --size 1 --duration 3600
+# Buy 1 ETH over 30 minutes (exchange handles slicing)
+openbroker twap --coin ETH --side buy --size 1 --duration 30
 
-# Custom intervals with randomization
-openbroker twap --coin BTC --side sell --size 0.5 --duration 1800 --intervals 6 --randomize 20
+# Sell 0.5 BTC over 2 hours without randomized timing
+openbroker twap --coin BTC --side sell --size 0.5 --duration 120 --randomize false
+
+# Cancel a running TWAP
+openbroker twap-cancel --coin ETH --twap-id 77738308
+
+# Check TWAP status
+openbroker twap-status --active
 ```
 
 ### Scale In/Out (Grid Orders)

package/bin/cli.ts

@@ -41,7 +41,9 @@ const commands: Record<string, { script: string; description: string }> = {
   'trigger': { script: 'operations/trigger-order.ts', description: 'Trigger order (TP/SL)' },
   'tpsl': { script: 'operations/set-tpsl.ts', description: 'Set TP/SL on position' },
   'cancel': { script: 'operations/cancel.ts', description: 'Cancel orders' },
-  'twap': { script: 'operations/twap.ts', description: 'TWAP execution' },
+  'twap': { script: 'operations/twap.ts', description: 'Native TWAP order' },
+  'twap-cancel': { script: 'operations/twap-cancel.ts', description: 'Cancel a TWAP order' },
+  'twap-status': { script: 'operations/twap-status.ts', description: 'View TWAP order status' },
   'scale': { script: 'operations/scale.ts', description: 'Scale in/out orders' },
   'bracket': { script: 'operations/bracket.ts', description: 'Bracket order (entry + TP + SL)' },
   'chase': { script: 'operations/chase.ts', description: 'Chase order with ALO' },
@@ -87,7 +89,9 @@ Trading Commands:
   cancel               Cancel orders
 
 Advanced Execution:
-  twap                 Time-weighted average price execution
+  twap                 Native TWAP order (exchange-managed)
+  twap-cancel          Cancel a running TWAP order
+  twap-status          View TWAP order history/status
   scale                Scale in/out with multiple orders
   bracket              Entry with TP and SL
   chase                Chase price with ALO orders

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.69",
+  "version": "1.0.71",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -35,6 +35,8 @@
     "set-tpsl": "tsx scripts/operations/set-tpsl.ts",
     "cancel": "tsx scripts/operations/cancel.ts",
     "twap": "tsx scripts/operations/twap.ts",
+    "twap-cancel": "tsx scripts/operations/twap-cancel.ts",
+    "twap-status": "tsx scripts/operations/twap-status.ts",
     "scale": "tsx scripts/operations/scale.ts",
     "bracket": "tsx scripts/operations/bracket.ts",
     "chase": "tsx scripts/operations/chase.ts",

package/scripts/core/client.ts

@@ -1126,7 +1126,18 @@ export class HyperliquidClient {
     const params: { user: string; dex?: string } = { user: user ?? this.address };
     if (dex !== undefined) params.dex = dex;
     const response = await this.info.clearinghouseState(params as any);
-    return response as ClearinghouseState;
+
+    // The SDK response has `withdrawable` as a top-level field, not inside
+    // marginSummary/crossMarginSummary. Copy it into our MarginSummary shape.
+    const state = response as unknown as ClearinghouseState;
+    const withdrawable = (response as any).withdrawable ?? '0';
+    if (state.marginSummary) {
+      state.marginSummary.withdrawable = withdrawable;
+    }
+    if (state.crossMarginSummary) {
+      state.crossMarginSummary.withdrawable = withdrawable;
+    }
+    return state;
   }
 
   /**
@@ -1142,6 +1153,7 @@ export class HyperliquidClient {
     const dexs = await this.getPerpDexs();
 
     // Collect positions from all HIP-3 dexes
+    let hip3Errors = 0;
     for (let i = 1; i < dexs.length; i++) {
       const dex = dexs[i];
       if (!dex) continue;
@@ -1156,22 +1168,32 @@ export class HyperliquidClient {
         if (!unified) {
           const dexMargin = dexState.marginSummary;
           if (dexMargin) {
+            const safeAdd = (a: string | undefined, b: string | undefined): string => {
+              const va = parseFloat(a ?? '0') || 0;
+              const vb = parseFloat(b ?? '0') || 0;
+              return String(va + vb);
+            };
             const addToSummary = (summary: { accountValue: string; totalNtlPos: string; totalRawUsd: string; totalMarginUsed: string; withdrawable: string }) => {
-              summary.accountValue = String(parseFloat(summary.accountValue) + parseFloat(dexMargin.accountValue));
-              summary.totalNtlPos = String(parseFloat(summary.totalNtlPos) + parseFloat(dexMargin.totalNtlPos));
-              summary.totalRawUsd = String(parseFloat(summary.totalRawUsd) + parseFloat(dexMargin.totalRawUsd));
-              summary.totalMarginUsed = String(parseFloat(summary.totalMarginUsed) + parseFloat(dexMargin.totalMarginUsed));
-              summary.withdrawable = String(parseFloat(summary.withdrawable) + parseFloat(dexMargin.withdrawable));
+              summary.accountValue = safeAdd(summary.accountValue, dexMargin.accountValue);
+              summary.totalNtlPos = safeAdd(summary.totalNtlPos, dexMargin.totalNtlPos);
+              summary.totalRawUsd = safeAdd(summary.totalRawUsd, dexMargin.totalRawUsd);
+              summary.totalMarginUsed = safeAdd(summary.totalMarginUsed, dexMargin.totalMarginUsed);
+              summary.withdrawable = safeAdd(summary.withdrawable, dexMargin.withdrawable);
             };
             addToSummary(mainState.marginSummary);
             addToSummary(mainState.crossMarginSummary);
           }
         }
       } catch (err) {
+        hip3Errors++;
         this.log(`Failed to fetch state for dex ${dex.name}:`, err instanceof Error ? err.message : String(err));
       }
     }
 
+    if (hip3Errors > 0) {
+      this.log(`Warning: ${hip3Errors} HIP-3 dex queries failed — some positions may be missing. Use --verbose for details.`);
+    }
+
     // For unified accounts: equity is the USDC balance from spot clearinghouse
     if (unified) {
       try {
@@ -1616,6 +1638,90 @@ export class HyperliquidClient {
       throw error;
     }
   }
+
+  /**
+   * Place a native Hyperliquid TWAP order.
+   * The exchange handles slicing and timing server-side.
+   * @param coin Asset symbol (e.g. "ETH")
+   * @param isBuy true for long, false for short
+   * @param size Total size in base currency
+   * @param durationMinutes Duration in minutes (5–1440)
+   * @param randomize Enable random order timing
+   * @param reduceOnly Reduce-only flag
+   * @param leverage Optional leverage to set before placing the TWAP
+   */
+  async twapOrder(
+    coin: string,
+    isBuy: boolean,
+    size: number,
+    durationMinutes: number,
+    randomize: boolean = true,
+    reduceOnly: boolean = false,
+    leverage?: number
+  ) {
+    await this.getMetaAndAssetCtxs();
+
+    if (leverage) {
+      await this.setLeverage(coin, leverage);
+    }
+
+    const assetIndex = this.getAssetIndex(coin);
+    const roundedSize = roundSize(size, this.getSzDecimals(coin));
+
+    this.log(`TWAP order: ${coin} (asset ${assetIndex}) ${isBuy ? 'BUY' : 'SELL'} ${roundedSize} over ${durationMinutes}m, randomize=${randomize}, reduceOnly=${reduceOnly}`);
+
+    try {
+      const response = await this.exchange.twapOrder({
+        twap: {
+          a: assetIndex,
+          b: isBuy,
+          s: String(roundedSize),
+          r: reduceOnly,
+          m: durationMinutes,
+          t: randomize,
+        },
+      });
+      this.log('TWAP order response:', JSON.stringify(response, null, 2));
+      return response;
+    } catch (error) {
+      this.log('TWAP order error:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Cancel a running TWAP order.
+   * @param coin Asset symbol (e.g. "ETH")
+   * @param twapId The TWAP order ID to cancel
+   */
+  async twapCancel(coin: string, twapId: number) {
+    await this.getMetaAndAssetCtxs();
+
+    const assetIndex = this.getAssetIndex(coin);
+
+    this.log(`TWAP cancel: ${coin} (asset ${assetIndex}) twapId=${twapId}`);
+
+    try {
+      const response = await this.exchange.twapCancel({
+        a: assetIndex,
+        t: twapId,
+      });
+      this.log('TWAP cancel response:', JSON.stringify(response, null, 2));
+      return response;
+    } catch (error) {
+      this.log('TWAP cancel error:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get TWAP order history for the current user.
+   */
+  async twapHistory() {
+    const response = await this.info.twapHistory({ user: this.address as `0x${string}` });
+    this.log('TWAP history:', JSON.stringify(response, null, 2));
+    return response;
+  }
 }
 
 // Singleton instance

package/scripts/info/account.ts

@@ -109,6 +109,13 @@ async function main() {
       console.log(`Builder Approved: ❌ No`);
       console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
     }
+
+    // Warn if API wallet setup looks misconfigured
+    if (!client.isApiWallet && accountValue === 0 && positions.length === 0) {
+      console.log('\n⚠️  No positions and $0 equity.');
+      console.log('   If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
+      console.log('   in ~/.openbroker/.env to the master account address (the wallet that holds funds).');
+    }
     console.log('');
 
     console.log('Margin Summary');

package/scripts/info/positions.ts

@@ -71,6 +71,10 @@ async function main() {
 
     if (positions.length === 0) {
       console.log(filterCoin ? `No position in ${filterCoin}` : 'No open positions');
+      if (!filterCoin && !client.isApiWallet) {
+        console.log('\n⚠️  If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
+        console.log('   in ~/.openbroker/.env to the master account address.');
+      }
       return;
     }
 

package/scripts/operations/twap-cancel.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env npx tsx
+// Cancel a running TWAP order
+
+import { getClient } from '../core/client.js';
+import { parseArgs } from '../core/utils.js';
+
+function printUsage() {
+  console.log(`
+Open Broker - Cancel TWAP Order
+================================
+
+Cancel a running native Hyperliquid TWAP order.
+
+Usage:
+  npx tsx scripts/operations/twap-cancel.ts --coin <COIN> --twap-id <ID>
+
+Options:
+  --coin        Asset symbol (e.g., ETH, BTC)
+  --twap-id     TWAP order ID to cancel
+  --verbose     Show debug output
+
+Examples:
+  npx tsx scripts/operations/twap-cancel.ts --coin ETH --twap-id 77738308
+`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const coin = args.coin as string;
+  const twapId = args['twap-id'] ? parseInt(args['twap-id'] as string) : NaN;
+
+  if (!coin || isNaN(twapId)) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const client = getClient();
+
+  if (args.verbose) {
+    client.verbose = true;
+  }
+
+  console.log('Open Broker - Cancel TWAP Order');
+  console.log('===============================\n');
+
+  try {
+    console.log(`Cancelling TWAP ${twapId} for ${coin}...`);
+
+    const response = await client.twapCancel(coin, twapId);
+
+    const status = response.response.data.status;
+    if (typeof status === 'string' && status === 'success') {
+      console.log(`\nTWAP order ${twapId} cancelled successfully.`);
+    } else if (typeof status === 'object' && 'error' in status) {
+      console.error(`\nFailed to cancel TWAP: ${status.error}`);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/operations/twap-status.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env npx tsx
+// View TWAP order history and status
+
+import { getClient } from '../core/client.js';
+import { formatUsd, parseArgs } from '../core/utils.js';
+
+function printUsage() {
+  console.log(`
+Open Broker - TWAP Status
+==========================
+
+View your TWAP order history and currently running TWAP orders.
+
+Usage:
+  npx tsx scripts/operations/twap-status.ts [--active]
+
+Options:
+  --active      Show only active (running) TWAP orders
+  --verbose     Show debug output
+
+Examples:
+  npx tsx scripts/operations/twap-status.ts            # All TWAP history
+  npx tsx scripts/operations/twap-status.ts --active    # Only running TWAPs
+`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const activeOnly = args.active as boolean;
+  const client = getClient();
+
+  if (args.verbose) {
+    client.verbose = true;
+  }
+
+  console.log('Open Broker - TWAP Status');
+  console.log('=========================\n');
+
+  try {
+    const history = await client.twapHistory();
+
+    if (history.length === 0) {
+      console.log('No TWAP orders found.');
+      return;
+    }
+
+    const filtered = activeOnly
+      ? history.filter(h => h.status.status === 'activated')
+      : history;
+
+    if (filtered.length === 0) {
+      console.log(activeOnly ? 'No active TWAP orders.' : 'No TWAP orders found.');
+      return;
+    }
+
+    console.log(`Found ${filtered.length} TWAP order${filtered.length > 1 ? 's' : ''}${activeOnly ? ' (active)' : ''}:\n`);
+
+    for (const entry of filtered) {
+      const { state, status, twapId } = entry;
+      const isBuy = state.side === 'B';
+      const executedSz = parseFloat(state.executedSz);
+      const totalSz = parseFloat(state.sz);
+      const executedNtl = parseFloat(state.executedNtl);
+      const avgPrice = executedSz > 0 ? executedNtl / executedSz : 0;
+      const pctDone = totalSz > 0 ? (executedSz / totalSz) * 100 : 0;
+
+      const statusLabel = status.status === 'activated' ? 'RUNNING'
+        : status.status === 'finished' ? 'FINISHED'
+        : status.status === 'terminated' ? 'CANCELLED'
+        : status.status === 'error' ? `ERROR: ${'description' in status ? status.description : ''}`
+        : status.status;
+
+      console.log(`  ${twapId !== undefined ? `TWAP #${twapId}` : 'TWAP'} — ${state.coin} ${isBuy ? 'BUY' : 'SELL'}`);
+      console.log(`    Status:     ${statusLabel}`);
+      console.log(`    Size:       ${executedSz} / ${totalSz} (${pctDone.toFixed(1)}%)`);
+      if (avgPrice > 0) {
+        console.log(`    Avg Price:  ${formatUsd(avgPrice)}`);
+        console.log(`    Notional:   ${formatUsd(executedNtl)}`);
+      }
+      console.log(`    Duration:   ${state.minutes}m, Randomize: ${state.randomize ? 'yes' : 'no'}`);
+      console.log(`    Started:    ${new Date(state.timestamp).toLocaleString()}`);
+      console.log('');
+    }
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/operations/twap.ts

@@ -1,67 +1,56 @@
 #!/usr/bin/env npx tsx
-// TWAP (Time-Weighted Average Price) execution
+// TWAP (Time-Weighted Average Price) execution using Hyperliquid's native TWAP orders
 
 import { getClient } from '../core/client.js';
-import { formatUsd, parseArgs, sleep } from '../core/utils.js';
+import { formatUsd, parseArgs } from '../core/utils.js';
 
 function printUsage() {
   console.log(`
-Open Broker - TWAP Order
-========================
+Open Broker - TWAP Order (Native)
+==================================
 
-Execute a large order over time using Time-Weighted Average Price strategy.
-Splits the order into smaller chunks and executes at regular intervals.
+Place a native Hyperliquid TWAP order. The exchange handles order slicing
+and execution timing server-side.
 
 Usage:
-  npx tsx scripts/operations/twap.ts --coin <COIN> --side <buy|sell> --size <SIZE> --duration <SECONDS>
+  npx tsx scripts/operations/twap.ts --coin <COIN> --side <buy|sell> --size <SIZE> --duration <MINUTES>
 
 Options:
   --coin        Asset to trade (e.g., ETH, BTC)
   --side        Order side: buy or sell
   --size        Total order size in base asset
-  --duration    Total execution time in seconds (e.g., 3600 for 1 hour)
-  --intervals   Number of slices (default: calculates based on duration)
-  --randomize   Randomize timing by ±X percent (default: 0)
-  --slippage    Slippage tolerance in bps per slice (default: 50)
-  --leverage    Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
-  --dry         Dry run - show execution plan without trading
+  --duration    Total execution time in minutes (5–1440, i.e. 5 min to 24 hours)
+  --randomize   Enable random order timing (default: true)
+  --reduce-only Reduce-only order (default: false)
+  --leverage    Set leverage (e.g., 10 for 10x)
+  --dry         Dry run - show order plan without executing
+  --verbose     Show debug output
 
 Examples:
-  # Execute 1 ETH buy over 1 hour (12 slices, every 5 min)
-  npx tsx scripts/operations/twap.ts --coin ETH --side buy --size 1 --duration 3600
+  # Execute 1 ETH buy over 30 minutes
+  npx tsx scripts/operations/twap.ts --coin ETH --side buy --size 1 --duration 30
 
-  # Execute 0.5 BTC sell over 30 min with 6 slices and 20% timing randomization
-  npx tsx scripts/operations/twap.ts --coin BTC --side sell --size 0.5 --duration 1800 --intervals 6 --randomize 20
+  # Execute 0.5 BTC sell over 2 hours without randomized timing
+  npx tsx scripts/operations/twap.ts --coin BTC --side sell --size 0.5 --duration 120 --randomize false
 
   # Preview execution plan
-  npx tsx scripts/operations/twap.ts --coin ETH --side buy --size 2 --duration 7200 --dry
+  npx tsx scripts/operations/twap.ts --coin ETH --side buy --size 2 --duration 60 --dry
 `);
 }
 
-interface TwapResult {
-  slice: number;
-  timestamp: Date;
-  size: number;
-  filled: number;
-  avgPrice: number;
-  status: 'filled' | 'partial' | 'failed';
-  error?: string;
-}
-
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
   const coin = args.coin as string;
   const side = args.side as string;
   const totalSize = parseFloat(args.size as string);
-  const duration = parseInt(args.duration as string);
-  const intervals = args.intervals ? parseInt(args.intervals as string) : Math.max(6, Math.floor(duration / 300)); // default: 1 slice per 5 min
-  const randomize = args.randomize ? parseInt(args.randomize as string) : 0;
-  const slippage = args.slippage ? parseInt(args.slippage as string) : undefined;
+  const durationMinutes = parseInt(args.duration as string);
+  const randomize = args.randomize === 'false' || args.randomize === false ? false : true;
+  const reduceOnly = args['reduce-only'] as boolean || false;
   const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const dryRun = args.dry as boolean;
 
-  if (!coin || !side || isNaN(totalSize) || isNaN(duration)) {
+  if (!coin || !side || isNaN(totalSize) || isNaN(durationMinutes)) {
     printUsage();
     process.exit(1);
   }
@@ -71,8 +60,13 @@ async function main() {
     process.exit(1);
   }
 
-  if (totalSize <= 0 || duration <= 0 || intervals <= 0) {
-    console.error('Error: size, duration, and intervals must be positive');
+  if (totalSize <= 0) {
+    console.error('Error: --size must be positive');
+    process.exit(1);
+  }
+
+  if (durationMinutes < 5 || durationMinutes > 1440) {
+    console.error('Error: --duration must be between 5 and 1440 minutes (5 min to 24 hours)');
     process.exit(1);
   }
 
@@ -83,11 +77,11 @@ async function main() {
     client.verbose = true;
   }
 
-  console.log('Open Broker - TWAP Execution');
-  console.log('============================\n');
+  console.log('Open Broker - Native TWAP Order');
+  console.log('===============================\n');
 
   try {
-    // Get current price for estimates
+    // Get current price for display
     const mids = await client.getAllMids();
     const midPrice = parseFloat(mids[coin]);
     if (!midPrice) {
@@ -95,120 +89,53 @@ async function main() {
       process.exit(1);
     }
 
-    const sliceSize = totalSize / intervals;
-    const baseInterval = (duration * 1000) / intervals; // ms between slices
     const notional = midPrice * totalSize;
 
-    console.log('Execution Plan');
-    console.log('--------------');
+    console.log('Order Details');
+    console.log('-------------');
     console.log(`Coin:           ${coin}`);
     console.log(`Side:           ${isBuy ? 'BUY' : 'SELL'}`);
     console.log(`Total Size:     ${totalSize}`);
     console.log(`Current Price:  ${formatUsd(midPrice)}`);
     console.log(`Est. Notional:  ${formatUsd(notional)}`);
-    console.log(`Duration:       ${formatDuration(duration)}`);
-    console.log(`Intervals:      ${intervals} slices`);
-    console.log(`Size/Slice:     ${sliceSize.toFixed(6)}`);
-    console.log(`Time/Slice:     ${formatDuration(duration / intervals)}`);
-    if (randomize > 0) {
-      console.log(`Randomization:  ±${randomize}%`);
+    console.log(`Duration:       ${formatDuration(durationMinutes * 60)}`);
+    console.log(`Randomize:      ${randomize ? 'yes' : 'no'}`);
+    console.log(`Reduce Only:    ${reduceOnly ? 'yes' : 'no'}`);
+    if (leverage) {
+      console.log(`Leverage:       ${leverage}x`);
     }
 
     if (dryRun) {
-      console.log('\n🔍 Dry run - showing execution schedule:\n');
-      let time = 0;
-      for (let i = 0; i < intervals; i++) {
-        const jitter = randomize > 0 ? (Math.random() - 0.5) * 2 * (randomize / 100) : 0;
-        const interval = baseInterval * (1 + jitter);
-        console.log(`  Slice ${i + 1}/${intervals}: ${sliceSize.toFixed(6)} @ T+${formatDuration(time / 1000)}`);
-        time += interval;
-      }
-      console.log(`\n  Total duration: ~${formatDuration(time / 1000)}`);
+      console.log('\nDry run - no order placed.');
+      console.log('The exchange will handle order slicing and timing automatically.');
       return;
     }
 
-    console.log('\nExecuting...\n');
-
-    const results: TwapResult[] = [];
-    let totalFilled = 0;
-    let totalCost = 0;
-    let startTime = Date.now();
-
-    for (let i = 0; i < intervals; i++) {
-      const sliceNum = i + 1;
-      console.log(`[${sliceNum}/${intervals}] Executing slice: ${sliceSize.toFixed(6)} ${coin}...`);
-
-      const result: TwapResult = {
-        slice: sliceNum,
-        timestamp: new Date(),
-        size: sliceSize,
-        filled: 0,
-        avgPrice: 0,
-        status: 'failed',
-      };
-
-      try {
-        const response = await client.marketOrder(coin, isBuy, sliceSize, slippage, leverage);
-
-        if (response.status === 'ok' && response.response && typeof response.response === 'object') {
-          const statuses = response.response.data.statuses;
-          for (const status of statuses) {
-            if (status.filled) {
-              result.filled = parseFloat(status.filled.totalSz);
-              result.avgPrice = parseFloat(status.filled.avgPx);
-              result.status = result.filled >= sliceSize * 0.99 ? 'filled' : 'partial';
-              totalFilled += result.filled;
-              totalCost += result.filled * result.avgPrice;
-              console.log(`  ✅ Filled ${result.filled} @ ${formatUsd(result.avgPrice)}`);
-            } else if (status.error) {
-              result.status = 'failed';
-              result.error = status.error;
-              console.log(`  ❌ Error: ${status.error}`);
-            }
-          }
-        } else {
-          result.status = 'failed';
-          result.error = typeof response.response === 'string' ? response.response : 'Unknown error';
-          console.log(`  ❌ Failed: ${result.error}`);
-        }
-      } catch (err) {
-        result.status = 'failed';
-        result.error = err instanceof Error ? err.message : String(err);
-        console.log(`  ❌ Error: ${result.error}`);
-      }
-
-      results.push(result);
-
-      // Wait for next interval (unless last slice)
-      if (i < intervals - 1) {
-        const jitter = randomize > 0 ? (Math.random() - 0.5) * 2 * (randomize / 100) : 0;
-        const waitTime = Math.max(1000, baseInterval * (1 + jitter));
-        console.log(`  Waiting ${formatDuration(waitTime / 1000)} until next slice...\n`);
-        await sleep(waitTime);
-      }
+    console.log('\nPlacing native TWAP order...\n');
+
+    const response = await client.twapOrder(
+      coin,
+      isBuy,
+      totalSize,
+      durationMinutes,
+      randomize,
+      reduceOnly,
+      leverage,
+    );
+
+    const status = response.response.data.status;
+    if ('running' in status) {
+      console.log(`TWAP order placed successfully!`);
+      console.log(`TWAP ID: ${status.running.twapId}`);
+      console.log(`\nThe exchange is now executing your TWAP order over ${formatDuration(durationMinutes * 60)}.`);
+      console.log(`To cancel: openbroker twap-cancel --coin ${coin} --twap-id ${status.running.twapId}`);
+      console.log(`To check status: openbroker twap-status`);
+    } else if ('error' in status) {
+      console.error(`TWAP order failed: ${status.error}`);
+      process.exit(1);
     }
-
-    // Summary
-    const endTime = Date.now();
-    const actualDuration = (endTime - startTime) / 1000;
-    const vwap = totalCost / totalFilled;
-    const currentPrice = parseFloat((await client.getAllMids())[coin]);
-    const slippageVsMid = isBuy
-      ? (vwap - midPrice) / midPrice
-      : (midPrice - vwap) / midPrice;
-
-    console.log('\n========== TWAP Summary ==========');
-    console.log(`Total Filled:    ${totalFilled.toFixed(6)} / ${totalSize} (${((totalFilled / totalSize) * 100).toFixed(1)}%)`);
-    console.log(`VWAP:            ${formatUsd(vwap)}`);
-    console.log(`Start Price:     ${formatUsd(midPrice)}`);
-    console.log(`End Price:       ${formatUsd(currentPrice)}`);
-    console.log(`Slippage vs Mid: ${(slippageVsMid * 10000).toFixed(1)} bps`);
-    console.log(`Total Cost:      ${formatUsd(totalCost)}`);
-    console.log(`Actual Duration: ${formatDuration(actualDuration)}`);
-    console.log(`Successful:      ${results.filter(r => r.status === 'filled').length}/${intervals} slices`);
-
   } catch (error) {
-    console.error('Error:', error);
+    console.error('Error:', error instanceof Error ? error.message : error);
     process.exit(1);
   }
 }

package/scripts/plugin/tools.ts

@@ -89,6 +89,11 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
           }));
         }
 
+        // Warn if likely misconfigured API wallet (querying the API wallet address instead of master)
+        if (!client.isApiWallet && accountValue === 0 && state.assetPositions.filter(ap => parseFloat(ap.position.szi) !== 0).length === 0) {
+          result.warning = 'No positions and $0 equity. If using an API wallet, ensure HYPERLIQUID_ACCOUNT_ADDRESS is set to the master account address in ~/.openbroker/.env or plugin config.';
+        }
+
         return json(result);
       },
     },
@@ -1226,35 +1231,137 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
 
     {
       name: 'ob_twap',
-      description: 'Execute a TWAP (time-weighted average price) order, splitting a large order into smaller slices over time. This is a long-running command.',
+      description: 'Place a native Hyperliquid TWAP order. The exchange handles order slicing and timing server-side. Returns immediately with a TWAP ID.',
       parameters: {
         type: 'object',
         properties: {
-          coin: { type: 'string', description: 'Asset symbol' },
+          coin: { type: 'string', description: 'Asset symbol (e.g., ETH, BTC)' },
           side: { type: 'string', enum: ['buy', 'sell'], description: 'Order direction' },
-          size: { type: 'number', description: 'Total order size' },
-          duration: { type: 'number', description: 'Duration in seconds' },
-          intervals: { type: 'number', description: 'Number of slices' },
-          randomize: { type: 'number', description: 'Randomize timing by this % (0-50)' },
+          size: { type: 'number', description: 'Total order size in base asset' },
+          duration: { type: 'number', description: 'Duration in minutes (5–1440)' },
+          randomize: { type: 'boolean', description: 'Randomize timing (default: true)' },
+          reduce_only: { type: 'boolean', description: 'Reduce-only order (default: false)' },
           leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x)' },
-          dry: { type: 'boolean', description: 'Preview without executing' },
         },
         required: ['coin', 'side', 'size', 'duration'],
       },
       async execute(_id, params) {
-        const { execFile } = await import('node:child_process');
-        const args = ['twap'];
-        for (const [key, value] of Object.entries(params)) {
-          if (value === undefined || value === null || value === false || value === '') continue;
-          if (value === true) args.push(`--${key}`);
-          else args.push(`--${key}`, String(value));
+        const { getClient } = await import('../core/client.js');
+        const coin = normalizeCoin(params.coin as string);
+        const isBuy = params.side === 'buy';
+        const size = params.size as number;
+        const durationMinutes = params.duration as number;
+        const randomize = params.randomize !== false;
+        const reduceOnly = params.reduce_only === true;
+        const leverage = params.leverage as number | undefined;
+
+        if (durationMinutes < 5 || durationMinutes > 1440) {
+          return error('Duration must be between 5 and 1440 minutes');
         }
 
-        return new Promise((resolve) => {
-          execFile('openbroker', args, { timeout: 600_000 }, (_err, stdout, stderr) => {
-            resolve({ content: [{ type: 'text' as const, text: (stdout + (stderr || '')).trim() }] });
-          });
-        });
+        try {
+          const client = getClient();
+          const mids = await client.getAllMids();
+          const midPrice = parseFloat(mids[coin]);
+
+          const response = await client.twapOrder(coin, isBuy, size, durationMinutes, randomize, reduceOnly, leverage);
+          const status = response.response.data.status;
+
+          if ('running' in status) {
+            return json({
+              twapId: status.running.twapId,
+              coin,
+              side: isBuy ? 'buy' : 'sell',
+              size,
+              durationMinutes,
+              randomize,
+              reduceOnly,
+              estimatedNotional: midPrice ? midPrice * size : undefined,
+              midPrice: midPrice || undefined,
+            });
+          } else if ('error' in status) {
+            return error(status.error);
+          }
+          return error('Unexpected response');
+        } catch (err) {
+          return error(err instanceof Error ? err.message : String(err));
+        }
+      },
+    },
+
+    {
+      name: 'ob_twap_cancel',
+      description: 'Cancel a running native Hyperliquid TWAP order by its TWAP ID.',
+      parameters: {
+        type: 'object',
+        properties: {
+          coin: { type: 'string', description: 'Asset symbol (e.g., ETH)' },
+          twap_id: { type: 'number', description: 'TWAP order ID to cancel' },
+        },
+        required: ['coin', 'twap_id'],
+      },
+      async execute(_id, params) {
+        const { getClient } = await import('../core/client.js');
+        const coin = normalizeCoin(params.coin as string);
+        const twapId = params.twap_id as number;
+
+        try {
+          const client = getClient();
+          const response = await client.twapCancel(coin, twapId);
+          const status = response.response.data.status;
+
+          if (typeof status === 'string' && status === 'success') {
+            return json({ cancelled: true, coin, twapId });
+          } else if (typeof status === 'object' && 'error' in status) {
+            return error(status.error);
+          }
+          return error('Unexpected response');
+        } catch (err) {
+          return error(err instanceof Error ? err.message : String(err));
+        }
+      },
+    },
+
+    {
+      name: 'ob_twap_status',
+      description: 'View TWAP order history and status. Shows active and past TWAP orders.',
+      parameters: {
+        type: 'object',
+        properties: {
+          active: { type: 'boolean', description: 'Only show active/running TWAP orders' },
+        },
+      },
+      async execute(_id, params) {
+        const { getClient } = await import('../core/client.js');
+
+        try {
+          const client = getClient();
+          const history = await client.twapHistory();
+
+          const filtered = params.active
+            ? history.filter((h: { status: { status: string } }) => h.status.status === 'activated')
+            : history;
+
+          return json(filtered.map((entry: {
+            twapId?: number;
+            state: { coin: string; side: string; sz: string; executedSz: string; executedNtl: string; minutes: number; randomize: boolean; reduceOnly: boolean; timestamp: number };
+            status: { status: string; description?: string };
+          }) => ({
+            twapId: entry.twapId,
+            coin: entry.state.coin,
+            side: entry.state.side === 'B' ? 'buy' : 'sell',
+            totalSize: entry.state.sz,
+            executedSize: entry.state.executedSz,
+            executedNotional: entry.state.executedNtl,
+            durationMinutes: entry.state.minutes,
+            randomize: entry.state.randomize,
+            reduceOnly: entry.state.reduceOnly,
+            status: entry.status.status,
+            startedAt: new Date(entry.state.timestamp).toISOString(),
+          })));
+        } catch (err) {
+          return error(err instanceof Error ? err.message : String(err));
+        }
       },
     },
 

package/scripts/setup/onboard.ts

@@ -231,34 +231,85 @@ async function main(): Promise<OnboardResult> {
 
   // Check if config already exists
   if (fs.existsSync(CONFIG_PATH)) {
-    console.log('⚠️  Config already exists!');
-    console.log(`   Location: ${CONFIG_PATH}\n`);
-
-    // Read existing config and show wallet address
     const envContent = fs.readFileSync(CONFIG_PATH, 'utf-8');
     const keyMatch = envContent.match(/HYPERLIQUID_PRIVATE_KEY=0x([a-fA-F0-9]{64})/);
 
-    if (keyMatch) {
-      const existingKey = `0x${keyMatch[1]}` as `0x${string}`;
-      const account = privateKeyToAccount(existingKey);
-      console.log('Current Configuration');
-      console.log('---------------------');
-      console.log(`Wallet Address: ${account.address}`);
-      console.log(`Config File:    ${CONFIG_PATH}`);
-      console.log(`\nTo reconfigure, delete the config file first:`);
-      console.log(`  rm ${CONFIG_PATH}`);
-      console.log(`\nTo fund this wallet, send USDC on Arbitrum, then deposit at:`);
-      console.log(`  https://app.hyperliquid.xyz/`);
-
+    if (!keyMatch) {
       return {
-        success: true,
-        walletAddress: account.address,
+        success: false,
+        error: 'Invalid config file - missing or malformed private key',
       };
     }
 
+    const existingKey = `0x${keyMatch[1]}` as `0x${string}`;
+    const account = privateKeyToAccount(existingKey);
+
+    // Check if this is an incomplete API wallet setup (HYPERLIQUID_ACCOUNT_ADDRESS missing or commented out)
+    const hasAccountAddress = /^HYPERLIQUID_ACCOUNT_ADDRESS=0x[a-fA-F0-9]{40}/m.test(envContent);
+    const isIncompleteApiWallet = envContent.includes('INCOMPLETE') || envContent.includes('# HYPERLIQUID_ACCOUNT_ADDRESS');
+
+    if (!hasAccountAddress && isIncompleteApiWallet) {
+      console.log('⚠️  Incomplete API wallet setup detected!');
+      console.log(`   API Wallet: ${account.address}`);
+      console.log(`   Master account address is missing — re-polling for approval...\n`);
+
+      const approveUrl = `${OPENBROKER_URL}/approve?agent=${account.address}`;
+      console.log(`   If not yet approved, visit: ${approveUrl}\n`);
+
+      const masterAddress = await pollForApproval(account.address);
+
+      if (masterAddress) {
+        console.log(`\n✅ Master wallet detected: ${masterAddress}`);
+
+        // Verify builder fee on-chain
+        console.log('   Verifying builder fee approval...');
+        const feeApproved = await verifyBuilderFee(masterAddress);
+        if (feeApproved) {
+          console.log('   ✅ Builder fee: approved on-chain');
+        } else {
+          console.log('   ⚠️  Builder fee not yet confirmed on-chain (may take a moment)');
+        }
+
+        // Save complete config
+        const completeEnv = buildApiWalletEnvContent(existingKey, masterAddress);
+        fs.writeFileSync(CONFIG_PATH, completeEnv, { mode: 0o600 });
+
+        console.log(`\n✅ Config updated: ${CONFIG_PATH}`);
+        console.log(`   API Wallet:     ${account.address}`);
+        console.log(`   Master Account: ${masterAddress}`);
+        console.log('\n   Start trading: openbroker account');
+
+        return { success: true, walletAddress: account.address };
+      }
+
+      console.log('\n⚠️  Approval still not completed.');
+      console.log(`   Visit: ${approveUrl}`);
+      console.log('   Then re-run: openbroker setup\n');
+      return { success: false, error: 'Approval not completed' };
+    }
+
+    // Config exists and is complete
+    console.log('⚠️  Config already exists!');
+    console.log(`   Location: ${CONFIG_PATH}\n`);
+    console.log('Current Configuration');
+    console.log('---------------------');
+    console.log(`Wallet Address: ${account.address}`);
+    if (hasAccountAddress) {
+      const addrMatch = envContent.match(/HYPERLIQUID_ACCOUNT_ADDRESS=(0x[a-fA-F0-9]+)/);
+      if (addrMatch) {
+        console.log(`Master Account: ${addrMatch[1]}`);
+        console.log(`Wallet Type:    API Wallet`);
+      }
+    }
+    console.log(`Config File:    ${CONFIG_PATH}`);
+    console.log(`\nTo reconfigure, delete the config file first:`);
+    console.log(`  rm ${CONFIG_PATH}`);
+    console.log(`\nTo fund this wallet, send USDC on Arbitrum, then deposit at:`);
+    console.log(`  https://app.hyperliquid.xyz/`);
+
     return {
-      success: false,
-      error: 'Invalid config file - missing or malformed private key',
+      success: true,
+      walletAddress: account.address,
     };
   }