openbroker 1.0.41 → 1.0.42

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: openbroker
-description: Hyperliquid trading CLI. Execute market orders, limit orders, manage positions, view funding rates, and run trading strategies. Use for any Hyperliquid perp trading task.
+description: Hyperliquid trading plugin with background position monitoring. Execute market orders, limit orders, manage positions, view funding rates, and run trading strategies with automatic alerts for PnL changes and liquidation risk.
 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.39", "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: Bash(openbroker:*) Bash(npm:*) Read
+metadata: {"author": "monemetrics", "version": "1.0.42", "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_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI

package/openclaw.plugin.json

@@ -0,0 +1,86 @@
+{
+  "id": "openbroker",
+  "name": "OpenBroker — Hyperliquid Trading",
+  "version": "1.0.0",
+  "description": "Trade on Hyperliquid DEX with background position monitoring",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "privateKey": {
+        "type": "string",
+        "description": "Hyperliquid wallet private key (0x-prefixed). Falls back to HYPERLIQUID_PRIVATE_KEY env var or ~/.openbroker/.env"
+      },
+      "accountAddress": {
+        "type": "string",
+        "description": "Master account address (for API wallets). Falls back to HYPERLIQUID_ACCOUNT_ADDRESS"
+      },
+      "network": {
+        "type": "string",
+        "enum": ["mainnet", "testnet"],
+        "default": "mainnet",
+        "description": "Network to use: mainnet or testnet"
+      },
+      "hooksToken": {
+        "type": "string",
+        "description": "Bearer token for gateway hooks endpoint (must match hooks.token in gateway config). Falls back to OPENCLAW_HOOKS_TOKEN env var."
+      },
+      "watcher": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable background position watcher"
+          },
+          "pollIntervalMs": {
+            "type": "number",
+            "default": 30000,
+            "description": "Poll interval in milliseconds"
+          },
+          "pnlChangeThresholdPct": {
+            "type": "number",
+            "default": 5,
+            "description": "Notify when unrealized PnL changes by this percentage"
+          },
+          "marginUsageWarningPct": {
+            "type": "number",
+            "default": 80,
+            "description": "Warn when margin usage exceeds this percentage"
+          },
+          "notifyOnPositionChange": {
+            "type": "boolean",
+            "default": true,
+            "description": "Send hook when positions open/close/change size"
+          },
+          "notifyOnFunding": {
+            "type": "boolean",
+            "default": true,
+            "description": "Send hook for funding rate alerts"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "privateKey": {
+      "label": "Private Key",
+      "sensitive": true,
+      "placeholder": "0x..."
+    },
+    "accountAddress": {
+      "label": "Account Address",
+      "placeholder": "0x..."
+    },
+    "network": {
+      "label": "Network",
+      "placeholder": "mainnet"
+    },
+    "hooksToken": {
+      "label": "Hooks Token",
+      "sensitive": true,
+      "placeholder": "your-hooks-secret"
+    }
+  }
+}

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "openbroker",
-  "version": "1.0.41",
+  "version": "1.0.42",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
     "openbroker": "./bin/openbroker.js"
   },
+  "openclaw": {
+    "extensions": ["./scripts/plugin/index.ts"]
+  },
   "files": [
     "bin/",
     "scripts/",
     "config/example.env",
+    "openclaw.plugin.json",
     "README.md",
     "CHANGELOG.md",
     "SKILL.md"

package/scripts/plugin/cli.ts

@@ -0,0 +1,127 @@
+// CLI commands for the OpenClaw plugin
+// Registered via api.registerCli with Commander.js-style program
+
+import type { PluginLogger, OpenClawPluginApi } from './types.js';
+import type { PositionWatcher } from './watcher.js';
+
+export function registerCliCommands(
+  api: OpenClawPluginApi,
+  watcher: PositionWatcher | null,
+  logger: PluginLogger,
+): void {
+  api.registerCli(({ program }) => {
+    const ob = program.command('ob').description('OpenBroker Hyperliquid trading tools');
+
+    ob
+      .command('watch')
+      .description('Start the position watcher in foreground (for debugging)')
+      .option('--interval <ms>', 'Poll interval in milliseconds', '30000')
+      .action(async (opts: unknown) => {
+        // If watcher is already running (gateway context), show its status
+        if (watcher && watcher.getStatus().running) {
+          const status = watcher.getStatus();
+          console.log('Position watcher is running as a background service.');
+          console.log(`Account:           ${status.accountAddress}`);
+          console.log(`Tracking           ${status.positions.length} position(s)`);
+          console.log(`Events detected:   ${status.eventsDetected}`);
+          console.log(`Last poll:         ${status.lastPollAt ?? 'Never'}`);
+          return;
+        }
+
+        // CLI context: start watcher in foreground for debugging
+        const { PositionWatcher: WatcherClass } = await import('./watcher.js');
+        const { interval: intervalStr } = opts as { interval: string };
+        const interval = parseInt(intervalStr, 10);
+
+        const fgWatcher = new WatcherClass({
+          logger,
+          gatewayPort: api.gatewayPort || 0,
+          pollIntervalMs: interval,
+          notifyOnPositionChange: api.gatewayPort > 0,
+        });
+
+        console.log('Starting position watcher in foreground...');
+        console.log(`Poll interval: ${interval / 1000}s`);
+        console.log('Press Ctrl+C to stop.\n');
+
+        process.on('SIGINT', async () => {
+          await fgWatcher.stop();
+          process.exit(0);
+        });
+
+        await fgWatcher.start();
+
+        // Keep alive
+        await new Promise(() => {});
+      });
+
+    ob
+      .command('status')
+      .description('Show position watcher status and current positions')
+      .action(async () => {
+        // If watcher is running in gateway context, show its live state
+        if (watcher && watcher.getStatus().running) {
+          const status = watcher.getStatus();
+
+          console.log('OpenBroker Position Watcher Status');
+          console.log('==================================\n');
+          console.log(`Running:           Yes (background service)`);
+          console.log(`Account:           ${status.accountAddress}`);
+          console.log(`Poll interval:     ${status.pollIntervalMs / 1000}s`);
+          console.log(`Events detected:   ${status.eventsDetected}`);
+          console.log(`Last poll:         ${status.lastPollAt ?? 'Never'}`);
+          console.log(`Equity:            $${status.equity ?? '?'}`);
+          console.log(`Margin used:       ${status.marginUsedPct?.toFixed(1) ?? '?'}%`);
+
+          if (status.positions.length === 0) {
+            console.log('\nNo open positions.');
+          } else {
+            console.log(`\nOpen Positions (${status.positions.length}):`);
+            for (const p of status.positions) {
+              const side = parseFloat(p.size) > 0 ? 'LONG' : 'SHORT';
+              console.log(`  ${p.coin} ${side}`);
+              console.log(`    Size:       ${p.size}`);
+              console.log(`    Entry:      $${p.entryPrice}`);
+              console.log(`    Unreal PnL: $${p.unrealizedPnl}`);
+              console.log(`    Liq Price:  ${p.liquidationPrice ? `$${p.liquidationPrice}` : 'N/A'}`);
+              console.log('');
+            }
+          }
+          return;
+        }
+
+        // CLI context: one-shot account query
+        console.log('OpenBroker Status (live query)\n');
+        try {
+          const { getClient } = await import('../core/client.js');
+          const { formatUsd } = await import('../core/utils.js');
+          const client = getClient();
+          const state = await client.getUserState();
+
+          console.log(`Account:  ${client.address}`);
+          console.log(`Equity:   ${formatUsd(parseFloat(state.marginSummary.accountValue))}`);
+          console.log(`Margin:   ${formatUsd(parseFloat(state.marginSummary.totalMarginUsed))}`);
+
+          const positions = state.assetPositions.filter(ap => parseFloat(ap.position.szi) !== 0);
+          if (positions.length === 0) {
+            console.log('\nNo open positions.');
+          } else {
+            console.log(`\nOpen Positions (${positions.length}):`);
+            for (const ap of positions) {
+              const p = ap.position;
+              const side = parseFloat(p.szi) > 0 ? 'LONG' : 'SHORT';
+              console.log(`  ${p.coin} ${side} ${p.szi} @ $${p.entryPx} | PnL: $${p.unrealizedPnl} | Liq: ${p.liquidationPx ?? 'N/A'}`);
+            }
+          }
+        } catch (err) {
+          console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+          console.log('\nRun "openbroker setup" to configure your wallet.');
+        }
+
+        if (watcher && !watcher.getStatus().running) {
+          console.log('\nNote: The background watcher is registered but not running.');
+          console.log('It starts automatically with the gateway. Use "openclaw ob watch" for foreground mode.');
+        }
+      });
+  }, { commands: ['ob'] });
+}

package/scripts/plugin/config-bridge.ts

@@ -0,0 +1,30 @@
+// Maps OpenClaw plugin config → process.env vars
+// Only sets vars that are not already defined (env vars take priority)
+
+import type { OpenBrokerPluginConfig } from './types.js';
+
+const CONFIG_MAP: Record<string, string> = {
+  privateKey: 'HYPERLIQUID_PRIVATE_KEY',
+  accountAddress: 'HYPERLIQUID_ACCOUNT_ADDRESS',
+  network: 'HYPERLIQUID_NETWORK',
+};
+
+/**
+ * Inject plugin config values into process.env if not already set.
+ *
+ * Priority chain:
+ * 1. Real env vars (highest — already in process.env)
+ * 2. Plugin config (injected here)
+ * 3. ~/.openbroker/.env (loaded by core/config.ts)
+ * 4. Hardcoded defaults in core/config.ts
+ */
+export function applyConfigBridge(pluginConfig: Record<string, unknown>): void {
+  const config = pluginConfig as OpenBrokerPluginConfig;
+
+  for (const [key, envVar] of Object.entries(CONFIG_MAP)) {
+    const value = config[key as keyof OpenBrokerPluginConfig];
+    if (value !== undefined && value !== null && typeof value !== 'object' && !process.env[envVar]) {
+      process.env[envVar] = String(value);
+    }
+  }
+}

package/scripts/plugin/index.ts

@@ -0,0 +1,57 @@
+// OpenClaw Plugin Entry Point for OpenBroker
+
+import type { OpenClawPluginApi, OpenBrokerPluginConfig } from './types.js';
+import { applyConfigBridge } from './config-bridge.js';
+import { PositionWatcher } from './watcher.js';
+import { createTools } from './tools.js';
+import { registerCliCommands } from './cli.js';
+
+export default {
+  id: 'openbroker',
+  name: 'OpenBroker — Hyperliquid Trading',
+
+  register(api: OpenClawPluginApi): void {
+    const { logger, gatewayPort } = api;
+    const pluginConfig = (api.pluginConfig ?? {}) as OpenBrokerPluginConfig;
+
+    // 1. Apply config bridge: inject plugin config → process.env
+    applyConfigBridge(pluginConfig as Record<string, unknown>);
+    logger.debug('OpenBroker config bridge applied');
+
+    // 2. Register background position watcher (unless disabled)
+    let watcher: PositionWatcher | null = null;
+    const watcherEnabled = pluginConfig.watcher?.enabled !== false;
+
+    if (watcherEnabled) {
+      watcher = new PositionWatcher({
+        logger,
+        gatewayPort,
+        hooksToken: pluginConfig.hooksToken,
+        accountAddress: pluginConfig.accountAddress
+          || process.env.HYPERLIQUID_ACCOUNT_ADDRESS
+          || undefined,
+        network: pluginConfig.network || process.env.HYPERLIQUID_NETWORK,
+        pollIntervalMs: pluginConfig.watcher?.pollIntervalMs,
+        pnlChangeThresholdPct: pluginConfig.watcher?.pnlChangeThresholdPct,
+        marginUsageWarningPct: pluginConfig.watcher?.marginUsageWarningPct,
+        notifyOnPositionChange: pluginConfig.watcher?.notifyOnPositionChange,
+        notifyOnFunding: pluginConfig.watcher?.notifyOnFunding,
+      });
+      api.registerService(watcher);
+      logger.debug('OpenBroker position watcher registered');
+    } else {
+      logger.debug('OpenBroker position watcher disabled by config');
+    }
+
+    // 3. Register agent tools
+    const tools = createTools(watcher);
+    for (const tool of tools) {
+      api.registerTool(tool);
+    }
+    logger.debug(`Registered ${tools.length} OpenBroker agent tools`);
+
+    // 4. Register CLI commands
+    registerCliCommands(api, watcher, logger);
+    logger.debug('OpenBroker CLI commands registered');
+  },
+};