OpenClaw Plugin

OpenBroker ships as an OpenClaw plugin. When installed, it registers structured agent tools and a background position watcher — the agent gets typed tool calls instead of raw Bash, and automatic alerts when positions move.

Install

Terminal

# From npm
openclaw plugins install openbroker
 
# Or link a local checkout (development)
openclaw plugins install -l ./open-broker-mvp

After installation, run openbroker setup to configure your wallet — the same onboarding flow as the standalone CLI.

Plugin Tools

The plugin registers 27 agent tools that call the Hyperliquid API directly through the core client. All trading tools support a dry parameter to preview before executing.

Category	Tool	Description
Info	ob_account	Account balance, equity, margin, open orders
Info	ob_positions	Open positions with PnL, leverage, liquidation
Info	ob_fills	Trade fill history with fees and realized PnL
Info	ob_orders	Order history (filled, canceled, open, etc.)
Info	ob_order_status	Check status of a specific order by ID
Info	ob_fees	Fee schedule, tier, maker/taker rates, volume
Info	ob_funding	Funding rates sorted by annualized rate
Info	ob_funding_history	Historical funding rates for an asset
Info	ob_candles	OHLCV candle data for an asset
Info	ob_trades	Recent trades (tape) for an asset
Info	ob_markets	Market data (price, volume, open interest)
Info	ob_search	Search assets across perps, HIP-3, spot
Info	ob_spot	Spot markets and token balances
Info	ob_rate_limit	API rate limit usage and capacity
Info	ob_funding_scan	Cross-dex funding scanner with pair detection
Trading	ob_buy	Market buy with slippage protection
Trading	ob_sell	Market sell with slippage protection
Trading	ob_limit	Limit order (GTC, IOC, or ALO)
Trading	ob_trigger	Trigger order (take profit / stop loss)
Trading	ob_tpsl	Set TP/SL on existing position
Trading	ob_cancel	Cancel orders (by coin, ID, or all)
Advanced	ob_twap	Native TWAP order (exchange-managed)
Advanced	ob_twap_cancel	Cancel a running TWAP order
Advanced	ob_twap_status	View TWAP order history and status
Advanced	ob_bracket	Entry + TP + SL in one command
Advanced	ob_chase	Chase price with ALO orders
Monitor	ob_watcher_status	Background watcher state and positions
Auto	ob_auto_run	Start a trading automation script
Auto	ob_auto_stop	Stop a running automation by ID
Auto	ob_auto_list	List available and running automations

Background Position Watcher

The plugin runs a background service that polls your Hyperliquid account and sends webhook notifications to your OpenClaw agent when something changes:

Position opened — new position detected
Position closed — position no longer present
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%)

Use ob_watcher_status to check the watcher state, tracked positions, and how many events have been detected.

Plugin Configuration

Configure the plugin in your OpenClaw settings under plugins.entries.openbroker.config. All fields are optional — the plugin falls back to ~/.openbroker/.env and environment variables.

openclaw.yaml — plugin config

plugins:
  entries:
    openbroker:
      enabled: true
      config:
        privateKey: "0x..."           # Falls back to HYPERLIQUID_PRIVATE_KEY
        accountAddress: "0x..."       # For API wallets
        network: "mainnet"            # mainnet or testnet
        hooksToken: "your-secret"     # Must match hooks.token below
        watcher:
          enabled: true
          pollIntervalMs: 30000       # Poll every 30s
          pnlChangeThresholdPct: 5    # Alert on 5%+ PnL change
          marginUsageWarningPct: 80   # Warn at 80% margin usage
          notifyOnPositionChange: true
          notifyOnFunding: true

Flag	Description	Default
privateKey	Hyperliquid wallet private key (0x-prefixed). Falls back to HYPERLIQUID_PRIVATE_KEY env var or ~/.openbroker/.env	—
accountAddress	Master account address (for API wallets). Falls back to HYPERLIQUID_ACCOUNT_ADDRESS	—
network	mainnet or testnet	mainnet
hooksToken	Bearer token for gateway hooks endpoint. Must match hooks.token in gateway config	—
watcher.enabled	Enable or disable the background position watcher	true
watcher.pollIntervalMs	How often to poll the Hyperliquid API (ms)	30000
watcher.pnlChangeThresholdPct	Minimum PnL change (% of position value) to trigger an alert	5
watcher.marginUsageWarningPct	Margin usage % above which to send a warning	80

Webhook Setup

For the position watcher to notify your agent, webhooks must be enabled in your OpenClaw gateway config:

openclaw.yaml — hooks

hooks:
  enabled: true
  token: "your-secret"   # Must match hooksToken in plugin config above

The watcher sends alerts to POST /hooks/agent with wakeMode: "now", which triggers an immediate agent turn. The agent receives a natural-language message like:

[OpenBroker Alert] Significant PnL movement on ETH: $500.00 → -$200.00 (14.0% of position value)
 
Details:
  coin: HYPE
  previousPnl: 500
  currentPnl: -200
  changePct: 14.0
  positionValue: 5000
 
Notify the user of this trading alert via their preferred channel.

The agent receives a structured alert with an explicit instruction to notify the user via their preferred channel (e.g., Slack, email, in-app notification). It can then decide to take action — adjust TP/SL, close the position, or simply forward the alert.

Plugin CLI Commands

The plugin also registers CLI commands accessible via the OpenClaw CLI:

Terminal

openclaw ob status    # Show watcher state and current positions
openclaw ob watch     # Run watcher in foreground (for debugging)

Configuration Reference