openbroker 1.0.54 → 1.0.55

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.0.55] - 2026-03-09
+
+### Added
+- **Leverage Control**: All trading commands now support `--leverage` flag to set leverage when opening positions
+  - Main perps: sets cross margin leverage before ordering
+  - HIP-3 perps: sets isolated margin at specified leverage (capped at asset's max)
+  - CLI: `--leverage 10` on `market`, `limit`, `trigger`, `bracket`, `chase`, `twap`, `scale`
+  - Plugin: `leverage` parameter on `ob_buy`, `ob_sell`, `ob_limit`, `ob_twap`, `ob_bracket`, `ob_chase`
+
 ## [1.0.54] - 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.54", "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.55", "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:*)
 ---
 

package/openclaw.plugin.json

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

package/package.json

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

package/scripts/core/client.ts

@@ -1127,18 +1127,20 @@ export class HyperliquidClient {
    * 1. Set isolated margin mode (required for HIP-3)
    * 2. Transfer USDC from main perp to the HIP-3 dex (each dex has its own balance)
    */
-  private async ensureHip3Ready(coin: string, notional: number): Promise<void> {
+  private async ensureHip3Ready(coin: string, notional: number, leverage?: number): Promise<void> {
     if (!this.isHip3(coin)) return;
 
     const dexInfo = this.coinDexMap.get(coin);
     if (!dexInfo?.dexName) return;
 
-    // Set isolated margin on first order per asset
-    if (!this.hip3IsolatedSet.has(coin)) {
-      const maxLev = this.hip3MaxLeverageMap.get(coin) ?? 10;
-      this.log(`HIP-3 asset ${coin} (dex: ${dexInfo.dexName}) — setting isolated margin at ${maxLev}x`);
+    const maxLev = this.hip3MaxLeverageMap.get(coin) ?? 10;
+    const effectiveLev = Math.min(leverage ?? maxLev, maxLev);
+
+    // Set isolated margin on first order per asset, or when leverage changes
+    if (!this.hip3IsolatedSet.has(coin) || leverage) {
+      this.log(`HIP-3 asset ${coin} (dex: ${dexInfo.dexName}) — setting isolated margin at ${effectiveLev}x`);
       try {
-        await this.updateLeverage(coin, maxLev, false); // false = isolated
+        await this.updateLeverage(coin, effectiveLev, false); // false = isolated
         this.hip3IsolatedSet.add(coin);
       } catch (err) {
         this.log(`Failed to set isolated margin for ${coin}:`, err instanceof Error ? err.message : String(err));
@@ -1147,8 +1149,7 @@ export class HyperliquidClient {
     }
 
     // Transfer USDC to the HIP-3 dex to cover margin
-    const maxLev = this.hip3MaxLeverageMap.get(coin) ?? 10;
-    const requiredMargin = notional / maxLev;
+    const requiredMargin = notional / effectiveLev;
     // Add 20% buffer for fees and slippage
     const transferAmount = Math.ceil(requiredMargin * 1.2 * 100) / 100;
 
@@ -1175,13 +1176,20 @@ export class HyperliquidClient {
     price: number,
     orderType: { limit: { tif: 'Gtc' | 'Ioc' | 'Alo' } },
     reduceOnly: boolean = false,
-    includeBuilder: boolean = true
+    includeBuilder: boolean = true,
+    leverage?: number
   ): Promise<OrderResponse> {
     this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
+    // Set leverage if specified (for main perps, cross margin; for HIP-3, handled in ensureHip3Ready)
+    if (leverage && !this.isHip3(coin)) {
+      this.log(`Setting leverage for ${coin} to ${leverage}x cross`);
+      await this.updateLeverage(coin, leverage, true);
+    }
+
     // HIP-3 perps: set isolated margin + transfer USDC to dex
-    await this.ensureHip3Ready(coin, size * price);
+    await this.ensureHip3Ready(coin, size * price, leverage);
 
     const assetIndex = this.getAssetIndex(coin);
     const szDecimals = this.getSzDecimals(coin);
@@ -1230,7 +1238,8 @@ export class HyperliquidClient {
     coin: string,
     isBuy: boolean,
     size: number,
-    slippageBps?: number
+    slippageBps?: number,
+    leverage?: number
   ): Promise<OrderResponse> {
     await this.getMetaAndAssetCtxs();
 
@@ -1256,7 +1265,8 @@ export class HyperliquidClient {
       limitPrice,
       { limit: { tif: 'Ioc' } },
       false,
-      true
+      true,
+      leverage
     );
   }
 
@@ -1266,7 +1276,8 @@ export class HyperliquidClient {
     size: number,
     price: number,
     tif: 'Gtc' | 'Ioc' | 'Alo' = 'Gtc',
-    reduceOnly: boolean = false
+    reduceOnly: boolean = false,
+    leverage?: number
   ): Promise<OrderResponse> {
     return this.order(
       coin,
@@ -1275,7 +1286,8 @@ export class HyperliquidClient {
       price,
       { limit: { tif } },
       reduceOnly,
-      true
+      true,
+      leverage
     );
   }
 
@@ -1296,13 +1308,20 @@ export class HyperliquidClient {
     triggerPrice: number,
     limitPrice: number,
     tpsl: 'tp' | 'sl',
-    reduceOnly: boolean = true
+    reduceOnly: boolean = true,
+    leverage?: number
   ): Promise<OrderResponse> {
     this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
+    // Set leverage if specified (for main perps)
+    if (leverage && !this.isHip3(coin)) {
+      this.log(`Setting leverage for ${coin} to ${leverage}x cross`);
+      await this.updateLeverage(coin, leverage, true);
+    }
+
     // HIP-3 perps: set isolated margin + transfer USDC to dex
-    await this.ensureHip3Ready(coin, size * limitPrice);
+    await this.ensureHip3Ready(coin, size * limitPrice, leverage);
 
     const assetIndex = this.getAssetIndex(coin);
     const szDecimals = this.getSzDecimals(coin);

package/scripts/operations/bracket.ts

@@ -24,6 +24,7 @@ Options:
   --tp          Take profit distance in % from entry
   --sl          Stop loss distance in % from entry
   --slippage    Slippage for market entry in bps (default: 50)
+  --leverage    Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
   --dry         Dry run - show bracket plan without executing
 
 Take Profit / Stop Loss:
@@ -66,6 +67,7 @@ async function main() {
   const tpPct = parseFloat(args.tp as string);
   const slPct = parseFloat(args.sl as string);
   const slippage = args.slippage ? parseInt(args.slippage as string) : undefined;
+  const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const dryRun = args.dry as boolean;
 
   if (!coin || !side || isNaN(size) || isNaN(tpPct) || isNaN(slPct)) {
@@ -171,7 +173,7 @@ async function main() {
     let actualEntry = entry;
 
     if (entryType === 'market') {
-      const entryResponse = await client.marketOrder(coin, isLong, size, slippage);
+      const entryResponse = await client.marketOrder(coin, isLong, size, slippage, leverage);
 
       if (entryResponse.status === 'ok' && entryResponse.response && typeof entryResponse.response === 'object') {
         const status = entryResponse.response.data.statuses[0];
@@ -189,7 +191,7 @@ async function main() {
         process.exit(1);
       }
     } else {
-      const entryResponse = await client.limitOrder(coin, isLong, size, entry, 'Gtc', false);
+      const entryResponse = await client.limitOrder(coin, isLong, size, entry, 'Gtc', false, leverage);
 
       if (entryResponse.status === 'ok' && entryResponse.response && typeof entryResponse.response === 'object') {
         const status = entryResponse.response.data.statuses[0];

package/scripts/operations/chase.ts

@@ -23,6 +23,7 @@ Options:
   --timeout     Max time to chase in seconds (default: 300 = 5 min)
   --interval    Update interval in ms (default: 2000)
   --max-chase   Max price to chase to in bps from start (default: 100 = 1%)
+  --leverage    Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
   --reduce      Reduce-only order
   --dry         Dry run - show chase parameters without executing
 
@@ -54,6 +55,7 @@ async function main() {
   const timeoutSec = args.timeout ? parseInt(args.timeout as string) : 300;
   const intervalMs = args.interval ? parseInt(args.interval as string) : 2000;
   const maxChaseBps = args['max-chase'] ? parseInt(args['max-chase'] as string) : 100;
+  const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const reduceOnly = args.reduce as boolean;
   const dryRun = args.dry as boolean;
 
@@ -168,7 +170,7 @@ async function main() {
         // Place new order
         process.stdout.write(`[${iteration}] Mid: ${formatUsd(currentMid)} → Order: ${formatUsd(orderPrice)}... `);
 
-        const response = await client.limitOrder(coin, isBuy, size, orderPrice, 'Alo', reduceOnly);
+        const response = await client.limitOrder(coin, isBuy, size, orderPrice, 'Alo', reduceOnly, leverage);
 
         if (response.status === 'ok' && response.response && typeof response.response === 'object') {
           const status = response.response.data.statuses[0];

package/scripts/operations/limit-order.ts

@@ -23,6 +23,7 @@ Options:
               GTC = Good Till Cancel (rests on book)
               IOC = Immediate Or Cancel (fills or cancels)
               ALO = Add Liquidity Only (post-only, maker only)
+  --leverage  Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
   --reduce    Reduce-only order (default: false)
   --dry       Dry run - show order details without executing
 
@@ -42,6 +43,7 @@ async function main() {
   const size = parseFloat(args.size as string);
   const price = parseFloat(args.price as string);
   const tifArg = (args.tif as string)?.toUpperCase() || 'GTC';
+  const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const reduceOnly = args.reduce as boolean;
   const dryRun = args.dry as boolean;
 
@@ -107,6 +109,7 @@ async function main() {
     console.log(`Notional:       ${formatUsd(notional)}`);
     console.log(`Time in Force:  ${tif}`);
     console.log(`Reduce Only:    ${reduceOnly ? 'Yes' : 'No'}`);
+    if (leverage) console.log(`Leverage:       ${leverage}x`);
     console.log(`Builder Fee:    ${client.builderInfo.f / 10} bps`);
 
     // Warning if order would be aggressively priced
@@ -121,7 +124,7 @@ async function main() {
 
     console.log('\nSubmitting...');
 
-    const response = await client.limitOrder(coin, isBuy, size, price, tif, reduceOnly);
+    const response = await client.limitOrder(coin, isBuy, size, price, tif, reduceOnly, leverage);
 
     console.log('\nResult');
     console.log('------');

package/scripts/operations/market-order.ts

@@ -19,6 +19,7 @@ Options:
   --side      Order side: buy or sell
   --size      Order size in base asset
   --slippage  Slippage tolerance in bps (default: from config, usually 50 = 0.5%)
+  --leverage  Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
   --reduce    Reduce-only order (default: false)
   --dry       Dry run - show order details without executing
   --verbose   Show full API request/response for debugging
@@ -44,6 +45,7 @@ async function main() {
   const side = args.side as string;
   const size = parseFloat(args.size as string);
   const slippage = args.slippage ? parseInt(args.slippage as string) : undefined;
+  const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const reduceOnly = args.reduce as boolean;
   const dryRun = args.dry as boolean;
 
@@ -103,6 +105,7 @@ async function main() {
     console.log(`Limit Price:  ${formatUsd(limitPrice)} (${slippageBps} bps slippage)`);
     console.log(`Notional:     ~${formatUsd(notional)}`);
     console.log(`Reduce Only:  ${reduceOnly ? 'Yes' : 'No'}`);
+    if (leverage) console.log(`Leverage:     ${leverage}x`);
     console.log(`Builder Fee:  ${client.builderInfo.f / 10} bps`);
 
     if (dryRun) {
@@ -112,7 +115,7 @@ async function main() {
 
     console.log('\nExecuting...');
 
-    const response = await client.marketOrder(coin, isBuy, size, slippage);
+    const response = await client.marketOrder(coin, isBuy, size, slippage, leverage);
 
     console.log('\nResult');
     console.log('------');

package/scripts/operations/scale.ts

@@ -25,6 +25,7 @@ Options:
                   - linear: more size at better prices
                   - exponential: much more size at better prices
                   - flat: equal size at all levels
+  --leverage      Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
   --reduce        Reduce-only orders (for scaling out of position)
   --tif           Time in force: GTC, ALO (default: GTC)
   --dry           Dry run - show order plan without executing
@@ -108,6 +109,7 @@ async function main() {
   const numLevels = parseInt(args.levels as string);
   const rangePct = parseFloat(args.range as string);
   const distribution = (args.distribution as string || 'linear') as 'linear' | 'exponential' | 'flat';
+  const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const reduceOnly = args.reduce as boolean;
   const tifArg = ((args.tif as string)?.toUpperCase() || 'GTC');
   const dryRun = args.dry as boolean;
@@ -208,7 +210,8 @@ async function main() {
           level.size,
           level.price,
           tif,
-          reduceOnly
+          reduceOnly,
+          leverage
         );
 
         if (response.status === 'ok' && response.response && typeof response.response === 'object') {

package/scripts/operations/trigger-order.ts

@@ -23,6 +23,7 @@ Options:
   --type        Order type: tp (take profit) or sl (stop loss)
   --limit       Limit price when triggered (default: trigger price for TP, with slippage for SL)
   --slippage    Slippage for SL in bps (default: 100 = 1%)
+  --leverage    Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3
   --reduce      Reduce-only order (default: true for TP/SL)
   --dry         Dry run - show order without placing
 
@@ -62,6 +63,7 @@ async function main() {
   const orderType = args.type as string;
   const limitPriceOverride = args.limit ? parseFloat(args.limit as string) : undefined;
   const slippageBps = args.slippage ? parseInt(args.slippage as string) : 100;
+  const leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const reduceOnly = args.reduce !== 'false'; // Default true
   const dryRun = args.dry as boolean;
 
@@ -167,7 +169,8 @@ async function main() {
       triggerPrice,
       limitPrice,
       tpsl,
-      reduceOnly
+      reduceOnly,
+      leverage
     );
 
     console.log('\nResult');

package/scripts/operations/twap.ts

@@ -23,6 +23,7 @@ Options:
   --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
 
 Examples:
@@ -57,6 +58,7 @@ async function main() {
   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 leverage = args.leverage ? parseInt(args.leverage as string) : undefined;
   const dryRun = args.dry as boolean;
 
   if (!coin || !side || isNaN(totalSize) || isNaN(duration)) {
@@ -146,7 +148,7 @@ async function main() {
       };
 
       try {
-        const response = await client.marketOrder(coin, isBuy, sliceSize, slippage);
+        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;

package/scripts/plugin/tools.ts

@@ -743,6 +743,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           coin: { type: 'string', description: 'Asset symbol (ETH, BTC, SOL, etc.)' },
           size: { type: 'number', description: 'Order size in base asset' },
           slippage: { type: 'number', description: 'Slippage tolerance in bps (default: 50)' },
+          leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3' },
           dry: { type: 'boolean', description: 'Preview without executing' },
         },
         required: ['coin', 'size'],
@@ -757,6 +758,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 leverage = params.leverage as number | undefined;
 
         const mids = await client.getAllMids();
         const midPrice = parseFloat(mids[coin]);
@@ -775,11 +777,12 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
             midPrice,
             slippagePrice,
             slippageBps,
+            leverage,
           });
         }
 
-        const result = await client.marketOrder(coin, true, parseFloat(roundedSize), slippageBps);
-        return json({ action: 'buy', coin, size: roundedSize, result });
+        const result = await client.marketOrder(coin, true, parseFloat(roundedSize), slippageBps, leverage);
+        return json({ action: 'buy', coin, size: roundedSize, leverage, result });
       },
     },
 
@@ -792,6 +795,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           coin: { type: 'string', description: 'Asset symbol (ETH, BTC, SOL, etc.)' },
           size: { type: 'number', description: 'Order size in base asset' },
           slippage: { type: 'number', description: 'Slippage tolerance in bps (default: 50)' },
+          leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3' },
           dry: { type: 'boolean', description: 'Preview without executing' },
         },
         required: ['coin', 'size'],
@@ -806,6 +810,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 leverage = params.leverage as number | undefined;
 
         const mids = await client.getAllMids();
         const midPrice = parseFloat(mids[coin]);
@@ -824,11 +829,12 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
             midPrice,
             slippagePrice,
             slippageBps,
+            leverage,
           });
         }
 
-        const result = await client.marketOrder(coin, false, parseFloat(roundedSize), slippageBps);
-        return json({ action: 'sell', coin, size: roundedSize, result });
+        const result = await client.marketOrder(coin, false, parseFloat(roundedSize), slippageBps, leverage);
+        return json({ action: 'sell', coin, size: roundedSize, leverage, result });
       },
     },
 
@@ -843,6 +849,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           size: { type: 'number', description: 'Order size in base asset' },
           price: { type: 'number', description: 'Limit price' },
           tif: { type: 'string', enum: ['GTC', 'IOC', 'ALO'], description: 'Time in force (default: GTC)' },
+          leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x). Cross for main perps, isolated for HIP-3' },
           reduce: { type: 'boolean', description: 'Reduce-only order' },
           dry: { type: 'boolean', description: 'Preview without executing' },
         },
@@ -860,6 +867,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const size = params.size as number;
         const price = params.price as number;
         const tif = ((params.tif as string) || 'GTC').toLowerCase();
+        const leverage = params.leverage as number | undefined;
         const reduceOnly = (params.reduce as boolean) || false;
 
         const szDecimals = await client.getSzDecimals(coin);
@@ -884,9 +892,9 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         }
 
         const result = await client.limitOrder(
-          coin, isBuy, parseFloat(roundedSize), parseFloat(roundedPrice), sdkTif, reduceOnly,
+          coin, isBuy, parseFloat(roundedSize), parseFloat(roundedPrice), sdkTif, reduceOnly, leverage,
         );
-        return json({ action: 'limit', coin, side: params.side, size: roundedSize, price: roundedPrice, result });
+        return json({ action: 'limit', coin, side: params.side, size: roundedSize, price: roundedPrice, leverage, result });
       },
     },
 
@@ -1068,6 +1076,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           duration: { type: 'number', description: 'Duration in seconds' },
           intervals: { type: 'number', description: 'Number of slices' },
           randomize: { type: 'number', description: 'Randomize timing by this % (0-50)' },
+          leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x)' },
           dry: { type: 'boolean', description: 'Preview without executing' },
         },
         required: ['coin', 'side', 'size', 'duration'],
@@ -1102,6 +1111,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           sl: { type: 'number', description: 'Stop loss percentage from entry' },
           entry: { type: 'string', enum: ['market', 'limit'], description: 'Entry type (default: market)' },
           price: { type: 'number', description: 'Entry price (required if entry=limit)' },
+          leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x)' },
           dry: { type: 'boolean', description: 'Preview without executing' },
         },
         required: ['coin', 'side', 'size', 'tp', 'sl'],
@@ -1134,6 +1144,7 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           size: { type: 'number', description: 'Order size' },
           offset: { type: 'number', description: 'Tick offset from best price (default: 1)' },
           timeout: { type: 'number', description: 'Timeout in seconds' },
+          leverage: { type: 'number', description: 'Set leverage (e.g., 10 for 10x)' },
           dry: { type: 'boolean', description: 'Preview without executing' },
         },
         required: ['coin', 'side', 'size'],