openbroker 1.0.41 → 1.0.43

package/README.md

@@ -559,6 +559,105 @@ openbroker approve-builder --max-fee "0.05%"  # Custom max fee
 | `--builder` | Custom builder address (advanced) | Open Broker |
 | `--verbose` | Show debug output | — |
 
+## OpenClaw Plugin
+
+OpenBroker ships as an [OpenClaw](https://openclaw.ai) plugin. When installed via OpenClaw, it registers structured agent tools and a background position watcher — no Bash wrappers needed.
+
+### Install via OpenClaw
+
+```bash
+openclaw plugins install openbroker
+```
+
+Or install from a local checkout during development:
+
+```bash
+openclaw plugins install -l ./open-broker-mvp
+```
+
+After installation, run `openbroker setup` to configure your wallet (same onboarding as the standalone CLI).
+
+### Plugin Tools
+
+When loaded, the plugin registers these agent tools:
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| Info | `ob_account` | Account balance, equity, margin, open orders |
+| Info | `ob_positions` | Open positions with PnL, leverage, liquidation price |
+| Info | `ob_funding` | Funding rates sorted by annualized rate |
+| Info | `ob_markets` | Market data (price, volume, OI) |
+| Info | `ob_search` | Search assets across perps, HIP-3, and spot |
+| Info | `ob_spot` | Spot markets and token balances |
+| Trading | `ob_buy` | Market buy |
+| Trading | `ob_sell` | Market sell |
+| Trading | `ob_limit` | Limit order (GTC, IOC, ALO) |
+| Trading | `ob_trigger` | Trigger order (TP/SL) |
+| Trading | `ob_tpsl` | Set TP/SL on existing position |
+| Trading | `ob_cancel` | Cancel orders |
+| Advanced | `ob_twap` | TWAP execution |
+| Advanced | `ob_bracket` | Entry + TP + SL |
+| Advanced | `ob_chase` | Chase price with ALO orders |
+| Monitoring | `ob_watcher_status` | Background watcher state |
+
+### Background Position Watcher
+
+The plugin runs a background service that polls your Hyperliquid account every 30 seconds and sends webhook notifications when:
+
+- **Position opened** — new position detected
+- **Position closed** — position removed
+- **Size changed** — position increased or decreased
+- **PnL threshold** — unrealized PnL changed by more than the configured % (default: 5%)
+- **Margin warning** — margin usage exceeds threshold (default: 80%)
+
+### Plugin Configuration
+
+Configure in your OpenClaw settings under `plugins.entries.openbroker.config`:
+
+```json
+{
+  "privateKey": "0x...",
+  "accountAddress": "0x...",
+  "network": "mainnet",
+  "hooksToken": "your-hooks-secret",
+  "watcher": {
+    "enabled": true,
+    "pollIntervalMs": 30000,
+    "pnlChangeThresholdPct": 5,
+    "marginUsageWarningPct": 80,
+    "notifyOnPositionChange": true,
+    "notifyOnFunding": true
+  }
+}
+```
+
+All fields are optional — the plugin falls back to `~/.openbroker/.env` and environment variables.
+
+### OpenClaw Webhook Setup
+
+For the position watcher to notify your agent, you need webhooks enabled in your OpenClaw gateway config:
+
+```yaml
+hooks:
+  enabled: true
+  token: "your-hooks-secret"   # Must match hooksToken in plugin config
+```
+
+The watcher sends alerts to `POST /hooks/agent` with `wakeMode: "now"`, which triggers an immediate agent turn. The agent receives a message like:
+
+```
+Position alert: ETH unrealized PnL changed from +$500 to -$200 (-140%).
+```
+
+### CLI Commands
+
+The plugin also registers CLI commands accessible via the OpenClaw CLI:
+
+```bash
+openclaw ob status    # Show watcher state and current positions
+openclaw ob watch     # Run watcher in foreground (debugging)
+```
+
 ## Development
 
 For local development without global install:

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.43", "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
@@ -321,6 +321,53 @@ Run `openbroker setup` to create the global config interactively.
 
 The builder fee (1 bps / 0.01%) is hardcoded and not configurable.
 
+## OpenClaw Plugin (Optional)
+
+This skill works standalone via Bash — every command above runs through the `openbroker` CLI. For enhanced features, the same `openbroker` npm package also ships as an **OpenClaw plugin** that you can enable alongside this skill.
+
+### What the plugin adds
+
+- **Structured agent tools** (`ob_account`, `ob_buy`, `ob_limit`, etc.) — typed tool calls with proper input schemas instead of Bash strings. The agent gets structured JSON responses.
+- **Background position watcher** — polls your Hyperliquid account every 30s and sends webhook alerts when positions open/close, PnL moves significantly, or margin usage gets dangerous.
+- **CLI commands** — `openclaw ob status` and `openclaw ob watch` for inspecting the watcher.
+
+### Enable the plugin
+
+The plugin is bundled in the same `openbroker` npm package. To enable it in your OpenClaw config:
+
+```yaml
+plugins:
+  entries:
+    openbroker:
+      enabled: true
+      config:
+        hooksToken: "your-hooks-secret"   # Required for watcher alerts
+        watcher:
+          enabled: true
+          pollIntervalMs: 30000
+          pnlChangeThresholdPct: 5
+          marginUsageWarningPct: 80
+```
+
+The plugin reads wallet credentials from `~/.openbroker/.env` (set up by `openbroker setup`), so you don't need to duplicate `privateKey` in the plugin config unless you want to override.
+
+### Webhook setup for watcher alerts
+
+For position alerts to reach the agent, enable hooks in your gateway config:
+
+```yaml
+hooks:
+  enabled: true
+  token: "your-hooks-secret"   # Must match hooksToken above
+```
+
+Without hooks, the watcher still runs and tracks state (accessible via `ob_watcher_status`), but it can't wake the agent.
+
+### Using with or without the plugin
+
+- **Skill only (no plugin):** Use Bash commands (`openbroker buy --coin ETH --size 0.1`). No background monitoring.
+- **Skill + plugin:** The agent prefers the `ob_*` tools when available (structured data), falls back to Bash for commands not covered by tools (strategies, scale). Background watcher sends alerts automatically.
+
 ## Risk Warning
 
 - Always use `--dry` first to preview orders

package/openclaw.plugin.json

@@ -0,0 +1,86 @@
+{
+  "id": "openbroker",
+  "name": "OpenBroker — Hyperliquid Trading",
+  "version": "1.0.43",
+  "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.43",
   "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');
+  },
+};