openbroker 1.0.68 → 1.0.70

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.68", "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.70", "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:*)
 ---
 
@@ -732,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
 

package/openclaw.plugin.json

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

package/package.json

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

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 {

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/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);
       },
     },

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,
     };
   }