openbroker 1.0.42 → 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

@@ -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.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)"}]}}
+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:*)
 ---
 
@@ -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

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

package/package.json

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