openbroker 1.0.49 → 1.0.52

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.0.52] - 2026-03-09
+
+### Fixed
+- **HIP-3 Trading: Isolated Margin**: HIP-3 perps require isolated margin mode (per Hyperliquid docs), but orders were sent without setting it — causing "Insufficient margin to place order" rejections. Now automatically sets isolated margin (3x or asset max, whichever is lower) on first order for each HIP-3 asset. Affects all trading commands: `buy`, `sell`, `market`, `limit`, `trigger`, `tpsl`, `bracket`, `chase`, `twap`, `scale`.
+
+## [1.0.51] - 2026-03-09
+
+### Added
+- **Watcher Poll Logging**: Position watcher now logs each poll cycle at debug level — shows position count, equity, and margin usage so you can confirm the watcher is running.
+
+## [1.0.50] - 2026-03-09
+
+### Fixed
+- **Plugin `ob_search` HIP-3 Results**: Fixed empty results for HIP-3 assets when using the `ob_search` plugin tool. Added type filter normalization (handles `HIP3`, `HIP-3`, `hip3`, `all`), added `enum` constraint to type parameter schema, surfaced errors instead of silently swallowing them, and aligned HIP-3 iteration with CLI search (index-based with null guards).
+- **SKILL.md**: Added "Finding Assets Before Trading" section instructing agents to always search for unfamiliar assets before trading, with examples of `ob_search` and `openbroker search`.
+
 ## [1.0.49] - 2026-03-09
 
 ### Fixed

package/SKILL.md

@@ -4,7 +4,7 @@ description: Hyperliquid trading plugin with background position monitoring. Exe
 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.49", "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.52", "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:*)
 ---
 
@@ -31,6 +31,21 @@ openbroker account
 openbroker buy --coin ETH --size 0.1
 ```
 
+## Important: Finding Assets Before Trading
+
+**Always search before trading an unfamiliar asset.** Hyperliquid has main perps (ETH, BTC, SOL...), HIP-3 perps (xyz:CL, xyz:GOLD, km:USOIL...), and spot markets. Use search to discover the correct ticker:
+
+```bash
+openbroker search --query GOLD              # Find all GOLD markets across all providers
+openbroker search --query oil               # Find oil-related assets (CL, BRENTOIL, USOIL...)
+openbroker search --query BTC --type perp   # BTC perps only
+openbroker search --query NATGAS --type hip3  # HIP-3 only
+```
+
+Or with the `ob_search` plugin tool: `{ "query": "gold" }` or `{ "query": "oil", "type": "hip3" }`
+
+**HIP-3 assets use `dex:COIN` format** — e.g., `xyz:CL` not just `CL`. If you get an error like "No market data found", search for the asset to find the correct prefixed ticker. Common HIP-3 dexes: `xyz`, `flx`, `km`, `hyna`, `vntl`, `cash`.
+
 ## Command Reference
 
 ### Setup

package/openclaw.plugin.json

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

package/package.json

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

package/scripts/core/client.ts

@@ -31,6 +31,10 @@ export class HyperliquidClient {
   private perpDexsCache: Array<{ name: string; fullName: string; deployer: string } | null> | null = null;
   /** Whether HIP-3 assets have been loaded into maps */
   private hip3Loaded: boolean = false;
+  /** HIP-3 assets that have had isolated margin set this session */
+  private hip3IsolatedSet: Set<string> = new Set();
+  /** Cached maxLeverage for HIP-3 assets */
+  private hip3MaxLeverageMap: Map<string, number> = new Map();
   public verbose: boolean = false;
 
   constructor(config?: OpenBrokerConfig) {
@@ -166,6 +170,7 @@ export class HyperliquidClient {
               this.assetMap.set(coinName, globalIndex);
               this.szDecimalsMap.set(coinName, asset.szDecimals);
               this.coinDexMap.set(coinName, { dexName: dex.name, dexIdx, localName });
+              if (asset.maxLeverage) this.hip3MaxLeverageMap.set(coinName, asset.maxLeverage);
             });
           }
         } catch (e) {
@@ -1074,6 +1079,38 @@ export class HyperliquidClient {
 
   // ============ Trading ============
 
+  /**
+   * HIP-3 perps require isolated margin mode. Automatically sets isolated margin
+   * with default leverage (3x) on first order for each HIP-3 asset this session.
+   */
+  private async ensureHip3Isolated(coin: string): Promise<void> {
+    if (!this.isHip3(coin)) return;
+    if (this.hip3IsolatedSet.has(coin)) return;
+
+    const dexInfo = this.coinDexMap.get(coin);
+    const maxLev = this.getHip3MaxLeverage(coin);
+    const leverage = Math.min(3, maxLev || 3);
+
+    this.log(`HIP-3 asset ${coin} (dex: ${dexInfo?.dexName}) — setting isolated margin at ${leverage}x`);
+    try {
+      await this.updateLeverage(coin, leverage, false); // false = isolated
+      this.hip3IsolatedSet.add(coin);
+    } catch (err) {
+      // Log but don't block — might already be set
+      this.log(`Failed to set isolated margin for ${coin}:`, err instanceof Error ? err.message : String(err));
+      this.hip3IsolatedSet.add(coin); // Don't retry every order
+    }
+  }
+
+  /**
+   * Get maxLeverage for a HIP-3 asset from cached metadata.
+   */
+  private getHip3MaxLeverage(coin: string): number | null {
+    // Already loaded via getMetaAndAssetCtxs → loadHip3Assets
+    // Check if we cached it during loadHip3Assets
+    return this.hip3MaxLeverageMap.get(coin) ?? null;
+  }
+
   async order(
     coin: string,
     isBuy: boolean,
@@ -1086,6 +1123,9 @@ export class HyperliquidClient {
     this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
+    // HIP-3 perps require isolated margin mode
+    await this.ensureHip3Isolated(coin);
+
     const assetIndex = this.getAssetIndex(coin);
     const szDecimals = this.getSzDecimals(coin);
 
@@ -1204,6 +1244,9 @@ export class HyperliquidClient {
     this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
+    // HIP-3 perps require isolated margin mode
+    await this.ensureHip3Isolated(coin);
+
     const assetIndex = this.getAssetIndex(coin);
     const szDecimals = this.getSzDecimals(coin);
 

package/scripts/plugin/tools.ts

@@ -200,7 +200,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         type: 'object',
         properties: {
           query: { type: 'string', description: 'Search query (e.g. GOLD, BTC, ETH)' },
-          type: { type: 'string', description: 'Filter by market type: perp, hip3, spot' },
+          type: { type: 'string', enum: ['perp', 'hip3', 'spot', 'all'], description: 'Filter by market type: perp, hip3, spot, or all (default: all)' },
         },
         required: ['query'],
       },
@@ -208,35 +208,42 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const { getClient } = await import('../core/client.js');
         const client = getClient();
         const query = (params.query as string).toUpperCase();
-        const typeFilter = params.type as string | undefined;
+        // Normalize type filter: lowercase, strip hyphens, treat "all" as no filter
+        const rawType = params.type ? String(params.type).toLowerCase().replace(/-/g, '') : undefined;
+        const typeFilter = rawType === 'all' ? undefined : rawType;
 
         const results: Array<Record<string, unknown>> = [];
+        const errors: string[] = [];
 
         // Search main perps
         if (!typeFilter || typeFilter === 'perp') {
-          const { meta, assetCtxs } = await client.getMetaAndAssetCtxs();
-          for (let i = 0; i < meta.universe.length; i++) {
-            const asset = meta.universe[i];
-            if (asset.name.toUpperCase().includes(query)) {
-              results.push({
-                coin: asset.name,
-                type: 'perp',
-                markPx: assetCtxs[i]?.markPx,
-                dayVolume: assetCtxs[i]?.dayNtlVlm,
-                maxLeverage: asset.maxLeverage,
-              });
+          try {
+            const { meta, assetCtxs } = await client.getMetaAndAssetCtxs();
+            for (let i = 0; i < meta.universe.length; i++) {
+              const asset = meta.universe[i];
+              if (asset.name.toUpperCase().includes(query)) {
+                results.push({
+                  coin: asset.name,
+                  type: 'perp',
+                  markPx: assetCtxs[i]?.markPx,
+                  dayVolume: assetCtxs[i]?.dayNtlVlm,
+                  maxLeverage: asset.maxLeverage,
+                });
+              }
             }
-          }
+          } catch (e) { errors.push(`perp: ${e instanceof Error ? e.message : String(e)}`); }
         }
 
         // Search HIP-3 perps
         if (!typeFilter || typeFilter === 'hip3' || typeFilter === 'perp') {
           try {
             const allPerps = await client.getAllPerpMetas();
-            for (const dexData of allPerps) {
-              if (!dexData.dexName) continue; // Skip main dex (already searched)
+            for (let dexIdx = 1; dexIdx < allPerps.length; dexIdx++) {
+              const dexData = allPerps[dexIdx];
+              if (!dexData || !dexData.meta?.universe) continue;
               for (let i = 0; i < dexData.meta.universe.length; i++) {
                 const asset = dexData.meta.universe[i];
+                if (!asset) continue;
                 if (asset.name.toUpperCase().includes(query)) {
                   results.push({
                     // API returns names already prefixed (e.g., "xyz:CL")
@@ -250,7 +257,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
                 }
               }
             }
-          } catch { /* HIP-3 may not be available */ }
+          } catch (e) { errors.push(`hip3: ${e instanceof Error ? e.message : String(e)}`); }
         }
 
         // Search spot
@@ -268,10 +275,12 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
                 });
               }
             }
-          } catch { /* spot may not be available */ }
+          } catch (e) { errors.push(`spot: ${e instanceof Error ? e.message : String(e)}`); }
         }
 
-        return json({ query, results });
+        const response: Record<string, unknown> = { query, results };
+        if (errors.length > 0) response.errors = errors;
+        return json(response);
       },
     },
 

package/scripts/plugin/watcher.ts

@@ -120,6 +120,12 @@ export class PositionWatcher implements PluginService {
       const state = await client.getUserState(this.accountAddress);
 
       const snapshot = this.buildSnapshot(state);
+
+      const posCount = snapshot.positions.size;
+      const equity = parseFloat(snapshot.equity).toFixed(2);
+      const marginPct = snapshot.marginUsedPct.toFixed(1);
+      this.logger.debug(`Poll: ${posCount} position(s), equity $${equity}, margin ${marginPct}%`);
+
       const events = this.seeded ? this.detectEvents(snapshot) : [];
 
       if (events.length > 0) {
@@ -128,6 +134,8 @@ export class PositionWatcher implements PluginService {
           this.logger.info(`[${event.type}] ${event.message}`);
           await this.sendHook(event);
         }
+      } else if (this.seeded) {
+        this.logger.debug('No position changes detected');
       }
 
       this.previousSnapshot = snapshot;