openbroker 1.0.40 → 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
@@ -39,10 +39,33 @@ openbroker setup              # One-command setup (wallet + config + builder app
 openbroker approve-builder --check  # Check builder fee status (for troubleshooting)
 ```
 
-The `setup` command handles everything:
-1. Generate new wallet or use existing private key
-2. Save config to `~/.openbroker/.env`
-3. Automatically approve builder fee (required for trading)
+The `setup` command offers three modes:
+1. **Import existing key** — use a private key you already have (master wallet)
+2. **Generate new wallet** — create a fresh master wallet
+3. **Generate API wallet** (recommended for agents) — creates a restricted wallet that can trade but cannot withdraw
+
+For options 1 and 2, setup saves config and approves the builder fee automatically.
+For option 3 (API wallet), see the API Wallet Setup section below.
+
+### API Wallet Setup (Recommended for Agents)
+
+API wallets can place trades on behalf of a master account but **cannot withdraw funds**. This is the safest option for automated agents.
+
+**Flow:**
+1. Run `openbroker setup` and choose option 3 ("Generate API wallet")
+2. The CLI generates a keypair and prints an approval URL (e.g. `https://openbroker.dev/approve?agent=0xABC...`)
+3. The agent owner opens the URL in a browser and connects their master wallet (MetaMask etc.)
+4. The master wallet signs two transactions: `ApproveAgent` (authorizes the API wallet) and `ApproveBuilderFee` (approves the 1 bps fee)
+5. The CLI detects the approval automatically and saves the config
+
+**After setup, the config will contain:**
+```
+HYPERLIQUID_PRIVATE_KEY=0x...        # API wallet private key
+HYPERLIQUID_ACCOUNT_ADDRESS=0x...    # Master account address
+HYPERLIQUID_NETWORK=mainnet
+```
+
+**Important for agents:** When using an API wallet, pass the approval URL to the agent owner (the human who controls the master wallet). The owner must approve in a browser before the agent can trade. The CLI waits up to 10 minutes for the approval. If it times out, re-run `openbroker setup`.
 
 ### Account Info
 ```bash
@@ -294,7 +317,9 @@ Run `openbroker setup` to create the global config interactively.
 |----------|----------|-------------|
 | `HYPERLIQUID_PRIVATE_KEY` | Yes | Wallet private key (0x...) |
 | `HYPERLIQUID_NETWORK` | No | `mainnet` (default) or `testnet` |
-| `HYPERLIQUID_ACCOUNT_ADDRESS` | No | For API wallets |
+| `HYPERLIQUID_ACCOUNT_ADDRESS` | No | Master account address (required for API wallets) |
+
+The builder fee (1 bps / 0.01%) is hardcoded and not configurable.
 
 ## Risk Warning
 

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.40",
+  "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/core/config.ts

@@ -109,9 +109,9 @@ export function loadConfig(): OpenBrokerConfig {
   const network = process.env.HYPERLIQUID_NETWORK || 'mainnet';
   const baseUrl = network === 'testnet' ? TESTNET_URL : MAINNET_URL;
 
-  // Use open-broker address by default, but allow override for custom builders
-  const builderAddress = (process.env.BUILDER_ADDRESS || OPEN_BROKER_BUILDER_ADDRESS).toLowerCase();
-  const builderFee = parseInt(process.env.BUILDER_FEE || '10', 10); // default 1 bps
+  // Builder fee is hardcoded — set by OpenBroker, not configurable by users
+  const builderAddress = OPEN_BROKER_BUILDER_ADDRESS.toLowerCase();
+  const builderFee = 10; // 10 tenths-of-bps = 1 bps = 0.01%
   const slippageBps = parseInt(process.env.SLIPPAGE_BPS || '50', 10); // default 0.5%
 
   // Derive the wallet address from private key

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