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.

OpenBroker is split across three npm packages so you only install what you need:

openbroker — the trading CLI itself. Standalone, works without OpenClaw.
openbroker-plugin — OpenClaw plugin packaging (manifest + agent tools + position watcher). Depends on openbroker.
openbroker-monitoring (optional) — dashboard / metrics forwarder. See Monitoring.

Install

As an OpenClaw plugin (recommended for agents)

Terminal

openclaw plugins install openbroker-plugin

This installs openbroker-plugin and pulls openbroker in as a transitive dependency. After install, run openbroker setup to configure your wallet.

Terminal

openbroker setup

CLI only (no agent integration)

If you just want the trading CLI — no OpenClaw, no agent tools — install the npm package globally:

Terminal

npm install -g openbroker
openbroker setup

You get the full set of trading commands (openbroker buy, openbroker auto run, etc.) without any of the plugin packaging. Useful for servers running automations standalone, or for local CLI use.

Skill only (no plugin runtime)

If your agent host doesn't go through OpenClaw — for example you want to load OpenBroker as a Claude Code skill — copy the SKILL.md from openbroker-plugin into your skill directory and install the CLI separately:

Terminal

# 1. Install the CLI so the skill's tool calls resolve
npm install -g openbroker
 
# 2. Drop the skill manifest where your agent looks for skills
curl -L https://raw.githubusercontent.com/aurracloud/openbroker-plugin/main/SKILL.md \
  -o ~/.claude/skills/openbroker/SKILL.md

The skill file declares the Bash(openbroker:*) tool surface and the env vars the agent needs to set. You don't get the position watcher this way (that's a plugin service) — but agents can still drive every CLI command.

Local development

For hacking on the plugin itself, link a local checkout:

Terminal

openclaw plugins install -l ./openbroker-plugin

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, and HIP-4 outcomes
Info	ob_spot	Spot markets and token balances
Info	ob_outcomes	HIP-4 outcome market search, details, and 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)
Trading	ob_outcome_buy	Buy a HIP-4 YES/NO outcome token
Trading	ob_outcome_sell	Sell or close a HIP-4 YES/NO outcome token
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 Monitoring