openbroker 1.0.57 → 1.0.59

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.0.59] - 2026-03-11
+
+### Fixed
+- **Plugin Tools Parity with CLI**: Reviewed all plugin tools against CLI commands and aligned behavior
+  - **`ob_account`**: Now uses `crossMarginSummary` (matches CLI), includes `signingWallet`, `walletType`, `marginRatio`, translates order sides (`B`→`buy`, `A`→`sell`), adds `side` field to positions
+  - **`ob_positions`**: Now fetches mark prices (`getAllMids`) and cumulative funding (`getUserFunding`) in parallel — includes `markPrice`, `notional`, `cumulativeFunding`, `liquidationDistance`, `maxLeverage`, `leverageType` fields matching CLI output
+  - **`ob_markets`**: Now includes HIP-3 markets (was main dex only), adds `change24h` field, sorts by volume, includes `type` field (`perp`/`hip3`)
+  - **`ob_buy`/`ob_sell`**: Fixed default slippage — was using `builderInfo.f` (1 bps) instead of config default (50 bps), causing market orders to fail with price-too-far errors
+
+### Added
+- **SKILL.md CLI Fallback Guide**: Added troubleshooting section with plugin tool → CLI command mapping table, so agents can fall back to CLI when plugin tools return errors
+
+## [1.0.58] - 2026-03-11
+
+### Fixed
+- **`ob_funding` HIP-3 Support**: Rewrote plugin tool to use `getMetaAndAssetCtxs()` + `getAllPerpMetas()` instead of `getPredictedFundings()` which only returned main dex data. Now correctly returns funding rates for HIP-3 assets like `xyz:GOLD`. Fixes "Cannot read properties of null" crash.
+- **`ob_search` HIP-3 Filter**: Fixed inverted type filter condition — HIP-3 search was gated behind `typeFilter === 'perp'` instead of `typeFilter === 'hip3'`, causing empty results in some filter combinations. Added `funding` and `openInterest` fields to search results.
+
 ## [1.0.57] - 2026-03-10
 
 ### 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.57", "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.59", "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:*)
 ---
 
@@ -46,6 +46,34 @@ Or with the `ob_search` plugin tool: `{ "query": "gold" }` or `{ "query": "oil",
 
 **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`.
 
+## Troubleshooting: CLI Fallback
+
+If an `ob_*` plugin tool returns unexpected errors, empty results, or crashes, **fall back to the equivalent CLI command** via Bash. The CLI and plugin tools share the same core code, but the CLI has more mature error handling and output.
+
+| Plugin Tool | CLI Equivalent |
+|-------------|---------------|
+| `ob_account` | `openbroker account --json` |
+| `ob_positions` | `openbroker positions --json` |
+| `ob_funding` | `openbroker funding --json --include-hip3` |
+| `ob_markets` | `openbroker markets --json --include-hip3` |
+| `ob_search` | `openbroker search --query <QUERY>` |
+| `ob_buy` | `openbroker buy --coin <COIN> --size <SIZE>` |
+| `ob_sell` | `openbroker sell --coin <COIN> --size <SIZE>` |
+| `ob_limit` | `openbroker limit --coin <COIN> --side <SIDE> --size <SIZE> --price <PRICE>` |
+| `ob_tpsl` | `openbroker tpsl --coin <COIN> --tp <PRICE> --sl <PRICE>` |
+| `ob_cancel` | `openbroker cancel --all` or `--coin <COIN>` |
+| `ob_fills` | `openbroker fills --json` |
+| `ob_orders` | `openbroker orders --json` |
+| `ob_funding_scan` | `openbroker funding-scan --json` |
+| `ob_candles` | `openbroker candles --coin <COIN> --json` |
+
+**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
+
+Add `--dry` to any trading CLI command to preview without executing. Add `--json` to info commands for structured output.
+
 ## Command Reference
 
 ### Setup

package/openclaw.plugin.json

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

package/package.json

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

package/scripts/plugin/tools.ts

@@ -37,18 +37,25 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const state = await client.getUserStateAll();
         const accountMode = await client.getAccountMode();
 
+        const margin = state.crossMarginSummary;
+        const accountValue = parseFloat(margin.accountValue);
+        const totalMarginUsed = parseFloat(margin.totalMarginUsed);
+
         const result: Record<string, unknown> = {
           address: client.address,
-          isApiWallet: client.isApiWallet,
+          signingWallet: client.walletAddress,
+          walletType: client.isApiWallet ? 'api' : 'main',
           accountMode,
-          equity: state.marginSummary.accountValue,
-          totalNtlPos: state.marginSummary.totalNtlPos,
-          totalMarginUsed: state.marginSummary.totalMarginUsed,
-          withdrawable: state.marginSummary.withdrawable,
+          equity: margin.accountValue,
+          totalNtlPos: margin.totalNtlPos,
+          totalMarginUsed: margin.totalMarginUsed,
+          withdrawable: margin.withdrawable,
+          marginRatio: totalMarginUsed > 0 && accountValue > 0 ? totalMarginUsed / accountValue : 0,
           positions: state.assetPositions
             .filter(ap => parseFloat(ap.position.szi) !== 0)
             .map(ap => ({
               coin: ap.position.coin,
+              side: parseFloat(ap.position.szi) > 0 ? 'long' : 'short',
               size: ap.position.szi,
               entryPrice: ap.position.entryPx,
               positionValue: ap.position.positionValue,
@@ -63,7 +70,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           result.openOrders = orders.map(o => ({
             coin: o.coin,
             oid: o.oid,
-            side: o.side,
+            side: o.side === 'B' ? 'buy' : 'sell',
             size: o.sz,
             price: o.limitPx,
             orderType: o.orderType,
@@ -87,22 +94,44 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
       async execute(_id, params) {
         const { getClient } = await import('../core/client.js');
         const client = getClient();
-        const state = await client.getUserStateAll();
+        const [state, mids, fundingHistory] = await Promise.all([
+          client.getUserStateAll(),
+          client.getAllMids(),
+          client.getUserFunding(),
+        ]);
+
+        // Sum cumulative funding per coin
+        const fundingByCoin = new Map<string, number>();
+        for (const entry of fundingHistory) {
+          const coin = entry.delta.coin;
+          const usdc = parseFloat(entry.delta.usdc);
+          fundingByCoin.set(coin, (fundingByCoin.get(coin) ?? 0) + usdc);
+        }
 
         let positions = state.assetPositions
           .filter(ap => parseFloat(ap.position.szi) !== 0)
-          .map(ap => ({
-            coin: ap.position.coin,
-            side: parseFloat(ap.position.szi) > 0 ? 'long' : 'short',
-            size: ap.position.szi,
-            entryPrice: ap.position.entryPx,
-            positionValue: ap.position.positionValue,
-            unrealizedPnl: ap.position.unrealizedPnl,
-            returnOnEquity: ap.position.returnOnEquity,
-            liquidationPx: ap.position.liquidationPx,
-            leverage: ap.position.leverage,
-            marginUsed: ap.position.marginUsed,
-          }));
+          .map(ap => {
+            const pos = ap.position;
+            const markPx = parseFloat(mids[pos.coin] || '0');
+            const liqPx = pos.liquidationPx ? parseFloat(pos.liquidationPx) : null;
+            return {
+              coin: pos.coin,
+              side: parseFloat(pos.szi) > 0 ? 'long' : 'short',
+              size: pos.szi,
+              entryPrice: pos.entryPx,
+              markPrice: markPx,
+              notional: Math.abs(parseFloat(pos.positionValue)),
+              unrealizedPnl: parseFloat(pos.unrealizedPnl),
+              returnOnEquity: parseFloat(pos.returnOnEquity),
+              cumulativeFunding: fundingByCoin.get(pos.coin) ?? 0,
+              marginUsed: parseFloat(pos.marginUsed),
+              leverage: `${pos.leverage.value}x`,
+              leverageType: pos.leverage.type,
+              liquidationPrice: liqPx,
+              liquidationDistance: liqPx && markPx ? Math.abs((markPx - liqPx) / markPx) : null,
+              maxLeverage: pos.maxLeverage,
+            };
+          });
 
         if (params.coin) {
           const coin = normalizeCoin(params.coin as string);
@@ -127,23 +156,59 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const { getClient } = await import('../core/client.js');
         const { annualizeFundingRate } = await import('../core/utils.js');
         const client = getClient();
-        const raw = await client.getPredictedFundings();
 
-        // raw is Array<[coin, Array<[venue, { fundingRate, nextFundingTime }]>]>
-        let results = raw.map(([coin, venues]) => {
-          // Use the first venue's funding rate
-          const rate = venues.length > 0 ? parseFloat(venues[0][1].fundingRate) : 0;
-          return {
-            coin,
-            fundingRate: rate,
-            annualizedRate: annualizeFundingRate(rate),
-            venues: venues.map(([venue, data]) => ({ venue, fundingRate: data.fundingRate })),
-          };
-        });
+        const filterCoin = params.coin ? normalizeCoin(params.coin as string) : undefined;
+        const includeHip3 = !filterCoin || filterCoin.includes(':');
 
-        if (params.coin) {
-          const coin = normalizeCoin(params.coin as string);
-          results = results.filter(r => r.coin === coin);
+        let results: Array<{ coin: string; fundingRate: number; annualizedRate: number; openInterest: string; markPx: string; type: string }> = [];
+
+        // Main dex funding from meta
+        try {
+          const { meta, assetCtxs } = await client.getMetaAndAssetCtxs();
+          for (let i = 0; i < meta.universe.length; i++) {
+            const asset = meta.universe[i];
+            const ctx = assetCtxs[i];
+            if (!ctx) continue;
+            if (filterCoin && asset.name !== filterCoin) continue;
+
+            const rate = parseFloat(ctx.funding);
+            results.push({
+              coin: asset.name,
+              fundingRate: rate,
+              annualizedRate: annualizeFundingRate(rate),
+              openInterest: ctx.openInterest,
+              markPx: ctx.markPx,
+              type: 'perp',
+            });
+          }
+        } catch { /* skip */ }
+
+        // HIP-3 dex funding
+        if (includeHip3) {
+          try {
+            const allPerps = await client.getAllPerpMetas();
+            for (let dexIdx = 1; dexIdx < allPerps.length; dexIdx++) {
+              const dexData = allPerps[dexIdx];
+              if (!dexData?.meta?.universe) continue;
+
+              for (let i = 0; i < dexData.meta.universe.length; i++) {
+                const asset = dexData.meta.universe[i];
+                const ctx = dexData.assetCtxs[i];
+                if (!asset || !ctx) continue;
+                if (filterCoin && asset.name !== filterCoin) continue;
+
+                const rate = parseFloat(ctx.funding);
+                results.push({
+                  coin: asset.name,
+                  fundingRate: rate,
+                  annualizedRate: annualizeFundingRate(rate),
+                  openInterest: ctx.openInterest,
+                  markPx: ctx.markPx,
+                  type: 'hip3',
+                });
+              }
+            }
+          } catch { /* skip */ }
         }
 
         results.sort((a, b) => Math.abs(b.annualizedRate) - Math.abs(a.annualizedRate));
@@ -157,7 +222,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
 
     {
       name: 'ob_markets',
-      description: 'View market data for Hyperliquid perpetuals (price, volume, open interest)',
+      description: 'View market data for Hyperliquid perpetuals (price, volume, open interest). Includes HIP-3 markets.',
       parameters: {
         type: 'object',
         properties: {
@@ -170,28 +235,75 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const client = getClient();
         const { meta, assetCtxs } = await client.getMetaAndAssetCtxs();
 
-        let markets = meta.universe.map((asset, i) => ({
-          coin: asset.name,
-          szDecimals: asset.szDecimals,
-          maxLeverage: asset.maxLeverage,
-          markPx: assetCtxs[i]?.markPx,
-          midPx: assetCtxs[i]?.midPx,
-          oraclePx: assetCtxs[i]?.oraclePx,
-          funding: assetCtxs[i]?.funding,
-          openInterest: assetCtxs[i]?.openInterest,
-          dayVolume: assetCtxs[i]?.dayNtlVlm,
-          prevDayPx: assetCtxs[i]?.prevDayPx,
-        }));
+        const filterCoin = params.coin ? normalizeCoin(params.coin as string) : undefined;
+        const includeHip3 = !filterCoin || filterCoin.includes(':');
+
+        interface MarketEntry { coin: string; type: string; markPx: number; oraclePx: number; change24h: number; dayVolume: number; openInterest: number; maxLeverage: number; szDecimals: number; funding: string }
+
+        const markets: MarketEntry[] = [];
+
+        // Main dex
+        for (let i = 0; i < meta.universe.length; i++) {
+          const asset = meta.universe[i];
+          const ctx = assetCtxs[i];
+          if (!ctx) continue;
+          if (filterCoin && asset.name !== filterCoin) continue;
+
+          const markPx = parseFloat(ctx.markPx);
+          const prevDayPx = parseFloat(ctx.prevDayPx);
+          markets.push({
+            coin: asset.name,
+            type: 'perp',
+            markPx,
+            oraclePx: parseFloat(ctx.oraclePx),
+            change24h: prevDayPx > 0 ? (markPx - prevDayPx) / prevDayPx : 0,
+            dayVolume: parseFloat(ctx.dayNtlVlm),
+            openInterest: parseFloat(ctx.openInterest),
+            maxLeverage: asset.maxLeverage,
+            szDecimals: asset.szDecimals,
+            funding: ctx.funding,
+          });
+        }
 
-        if (params.coin) {
-          const coin = normalizeCoin(params.coin as string);
-          markets = markets.filter(m => m.coin === coin);
+        // HIP-3 dexes
+        if (includeHip3) {
+          try {
+            const allPerps = await client.getAllPerpMetas();
+            for (let dexIdx = 1; dexIdx < allPerps.length; dexIdx++) {
+              const dexData = allPerps[dexIdx];
+              if (!dexData?.meta?.universe) continue;
+              for (let i = 0; i < dexData.meta.universe.length; i++) {
+                const asset = dexData.meta.universe[i];
+                const ctx = dexData.assetCtxs[i];
+                if (!asset || !ctx) continue;
+                if (filterCoin && asset.name !== filterCoin) continue;
+
+                const markPx = parseFloat(ctx.markPx);
+                const prevDayPx = parseFloat(ctx.prevDayPx);
+                markets.push({
+                  coin: asset.name,
+                  type: 'hip3',
+                  markPx,
+                  oraclePx: parseFloat(ctx.oraclePx),
+                  change24h: prevDayPx > 0 ? (markPx - prevDayPx) / prevDayPx : 0,
+                  dayVolume: parseFloat(ctx.dayNtlVlm),
+                  openInterest: parseFloat(ctx.openInterest),
+                  maxLeverage: asset.maxLeverage,
+                  szDecimals: asset.szDecimals,
+                  funding: ctx.funding,
+                });
+              }
+            }
+          } catch { /* skip */ }
         }
 
+        // Sort by volume (matches CLI behavior)
+        markets.sort((a, b) => b.dayVolume - a.dayVolume);
+
         const top = (params.top as number) || 30;
-        markets = markets.slice(0, top);
+        const result = filterCoin ? markets : markets.slice(0, top);
 
-        return json({ markets });
+        return json({ markets: result });
       },
     },
 
@@ -228,7 +340,9 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
                   coin: asset.name,
                   type: 'perp',
                   markPx: assetCtxs[i]?.markPx,
+                  funding: assetCtxs[i]?.funding,
                   dayVolume: assetCtxs[i]?.dayNtlVlm,
+                  openInterest: assetCtxs[i]?.openInterest,
                   maxLeverage: asset.maxLeverage,
                 });
               }
@@ -236,24 +350,26 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           } catch (e) { errors.push(`perp: ${e instanceof Error ? e.message : String(e)}`); }
         }
 
-        // Search HIP-3 perps
-        if (!typeFilter || typeFilter === 'hip3' || typeFilter === 'perp') {
+        // Search HIP-3 perps (always included unless filtering to perp-only or spot-only)
+        if (!typeFilter || typeFilter === 'hip3') {
           try {
             const allPerps = await client.getAllPerpMetas();
             for (let dexIdx = 1; dexIdx < allPerps.length; dexIdx++) {
               const dexData = allPerps[dexIdx];
-              if (!dexData || !dexData.meta?.universe) continue;
+              if (!dexData?.meta?.universe) continue;
               for (let i = 0; i < dexData.meta.universe.length; i++) {
                 const asset = dexData.meta.universe[i];
+                const ctx = dexData.assetCtxs[i];
                 if (!asset) continue;
                 if (asset.name.toUpperCase().includes(query)) {
                   results.push({
-                    // API returns names already prefixed (e.g., "xyz:CL")
                     coin: asset.name,
                     type: 'hip3',
                     dex: dexData.dexName,
-                    markPx: dexData.assetCtxs[i]?.markPx,
-                    dayVolume: dexData.assetCtxs[i]?.dayNtlVlm,
+                    markPx: ctx?.markPx,
+                    funding: ctx?.funding,
+                    dayVolume: ctx?.dayNtlVlm,
+                    openInterest: ctx?.openInterest,
                     maxLeverage: asset.maxLeverage,
                   });
                 }
@@ -759,7 +875,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
 
         const coin = normalizeCoin(params.coin as string);
         const size = params.size as number;
-        const slippageBps = (params.slippage as number) ?? client.builderInfo.f;
+        const slippageBps = params.slippage as number | undefined;
         const leverage = params.leverage as number | undefined;
 
         const mids = await client.getAllMids();
@@ -768,7 +884,8 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
 
         const szDecimals = await client.getSzDecimals(coin);
         const roundedSize = roundSize(size, szDecimals);
-        const slippagePrice = getSlippagePrice(midPrice, true, slippageBps);
+        const effectiveSlippage = slippageBps ?? 50;
+        const slippagePrice = getSlippagePrice(midPrice, true, effectiveSlippage);
 
         if (params.dry) {
           return json({
@@ -778,7 +895,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
             size: roundedSize,
             midPrice,
             slippagePrice,
-            slippageBps,
+            slippageBps: effectiveSlippage,
             leverage,
           });
         }
@@ -811,7 +928,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
 
         const coin = normalizeCoin(params.coin as string);
         const size = params.size as number;
-        const slippageBps = (params.slippage as number) ?? client.builderInfo.f;
+        const slippageBps = params.slippage as number | undefined;
         const leverage = params.leverage as number | undefined;
 
         const mids = await client.getAllMids();
@@ -820,7 +937,8 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
 
         const szDecimals = await client.getSzDecimals(coin);
         const roundedSize = roundSize(size, szDecimals);
-        const slippagePrice = getSlippagePrice(midPrice, false, slippageBps);
+        const effectiveSlippage = slippageBps ?? 50;
+        const slippagePrice = getSlippagePrice(midPrice, false, effectiveSlippage);
 
         if (params.dry) {
           return json({
@@ -830,7 +948,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
             size: roundedSize,
             midPrice,
             slippagePrice,
-            slippageBps,
+            slippageBps: effectiveSlippage,
             leverage,
           });
         }