openbroker

Open Broker

Hyperliquid trading CLI. Execute orders, manage positions, and run trading strategies on Hyperliquid DEX.

Installation

npm install -g openbroker

Companion packages

OpenBroker manages optional, allowlisted companion packages through the same CLI:

openbroker install --list        # Show supported packages
openbroker install monitoring    # Local automation dashboard
openbroker install extended      # Extended Exchange CLI

The command installs globally through npm so each package's executable is available on your PATH. Re-run the same command to upgrade to the latest release, or pin a release with --tag <version>. Use --dry to preview the npm command.

Codex: one-command install

Install the Codex skill, persistent CLI, and restricted API-wallet onboarding flow:

npx openbroker@latest install --codex

When the command prints an approval URL, open it and connect the funded master Hyperliquid account you want OpenBroker to trade on. Restart Codex or start a new thread when setup finishes, then invoke $openbroker.

Quick Start

# 1. Setup a restricted API wallet (recommended for agents)
openbroker setup --api-wallet

# 2. Open the printed approval link and connect your funded master Hyperliquid wallet

# 3. Start trading
openbroker account                          # View account info
openbroker buy --coin ETH --size 0.1        # Market buy
openbroker search --query GOLD              # Find markets

Commands

Setup

npx openbroker@latest install --codex  # Codex skill + CLI + API-wallet onboarding
openbroker install --list       # List optional companion packages
openbroker install monitoring   # Install or upgrade openbroker-monitoring
openbroker install extended     # Install or upgrade openbroker-extended
openbroker setup --api-wallet   # Recommended: restricted agent wallet + browser approval
openbroker setup                # Interactive; API wallet is the default

The setup command handles everything automatically:

• Generates a restricted API wallet by default, or accepts another wallet mode interactively
• Saves configuration to ~/.openbroker/.env (permissions 0600)
• Prints a browser approval link and waits for master-wallet authorization

Setup offers three modes:

1. Generate fresh wallet — separately funded wallet, no browser steps
2. Import existing key — use a key you already have
3. Generate API wallet (default and recommended for agents) — can trade but cannot withdraw; requires browser approval from a master wallet

---

Info Commands

account — View Account Info

Show balance, equity, margin, and positions summary.

openbroker account              # Balance, equity, margin, positions
openbroker account --orders     # Also show open orders

Flag	Description	Default
--orders	Include open orders in the output	—

positions — View Positions

Detailed position view with entry/mark prices, PnL, leverage, liquidation distance, and margin used.

openbroker positions             # All open positions
openbroker positions --coin ETH  # Single position detail

Flag	Description	Default
--coin	Filter to a single asset	—

funding — Funding Rates

View funding rates sorted by annualized rate. Highlights high-funding opportunities.

openbroker funding              # Top 20 by annualized rate
openbroker funding --top 50     # Top 50
openbroker funding --coin ETH   # Single asset
openbroker funding --sort oi    # Sort by open interest

Flag	Description	Default
--top	Number of results to show	20
--coin	Filter to a single asset	—
--sort	Sort by: annualized, hourly, or oi	annualized
--all	Show all assets including low OI	—

markets — Market Data

Market data for perpetuals. Pass --coin for a detailed single-asset view with oracle price, min size, and more.

openbroker markets              # Top 30 perps by volume
openbroker markets --coin ETH   # Detailed view for ETH
openbroker markets --sort change --top 10  # Top movers

Flag	Description	Default
--coin	Detailed view for a single asset	—
--top	Number of results	30
--sort	Sort by: volume, oi, or change	volume

all-markets — All Markets

Browse all available markets across main perps, HIP-3 perps, spot, and HIP-4 outcomes — grouped by type.

openbroker all-markets                # Everything
openbroker all-markets --type perp    # Main perps only
openbroker all-markets --type hip3    # HIP-3 perps only
openbroker all-markets --type spot    # Spot only
openbroker all-markets --type outcome # HIP-4 outcomes only
openbroker all-markets --top 20       # Top 20 by volume

Flag	Description	Default
--type	Filter: perp, spot, hip3, outcome, or all	all
--top	Limit to top N by volume	—
--verbose	Show detailed output	—

search — Search Markets

Search for assets by name across all providers (perps, HIP-3, spot, HIP-4 outcomes). Shows funding comparison when an asset is listed on multiple venues.

openbroker search --query GOLD             # Find all GOLD markets
openbroker search --query ETH --type perp  # ETH perps only
openbroker search --query PURR --type spot # PURR spot only
openbroker search --query BTC --type outcome # HIP-4 outcomes only

Flag	Description	Default
--query	Search term (matches coin name)	required
--type	Filter: perp, spot, hip3, outcome, or all	all
--verbose	Show detailed output	—

spot — Spot Markets & Balances

openbroker spot                  # All spot markets
openbroker spot --balances       # Your spot token balances
openbroker spot --coin PURR      # Filter by coin
openbroker spot --top 20         # Top 20 by volume

Flag	Description	Default
--balances	Show your spot token balances instead of markets	—
--coin	Filter by coin symbol	—
--top	Limit to top N by volume	—
--verbose	Show token metadata	—

outcomes — HIP-4 Outcome Markets

Search and inspect prediction/outcome markets. Outcome sides use Hyperliquid's encoded spot-like coin form: #<encoding>, where encoding = 10 * outcomeId + side; side 0 is usually YES and side 1 is usually NO.

openbroker outcomes --query BTC
openbroker outcomes --outcome 123
openbroker outcomes --outcome 123 --side yes --json
openbroker outcomes --balances

Flag	Description	Default
--query	Search market name, description, underlying, expiry, or target price	—
--outcome	Outcome id, #<encoding>, or +<encoding>	—
--side	Outcome side for plain ids: yes, no, 0, or 1	yes
--balances	Show outcome token balances	—
--top	Limit to top N matches	—
--json	Machine-readable output	—

fills — Trade Fill History

View your trade executions with prices, fees, and realized PnL.

openbroker fills                          # Recent fills
openbroker fills --coin ETH               # ETH fills only
openbroker fills --coin BTC --side buy --top 50

Flag	Description	Default
--coin	Filter by coin symbol	—
--side	Filter by side: buy or sell	—
--top	Number of recent fills to show	20

orders — Order History

View all historical orders including filled, canceled, and rejected. Use --open to show only currently open orders.

openbroker orders                         # Recent orders
openbroker orders --open                  # Currently open orders only
openbroker orders --open --coin ETH       # Open orders for a specific coin
openbroker orders --coin ETH --status filled
openbroker orders --top 50

Flag	Description	Default
--coin	Filter by coin symbol	—
--status	Filter by status (filled, canceled, open, triggered, etc.)	—
--open	Show only currently open orders	—
--top	Number of recent orders to show	20

order-status — Check Order Status

Look up the status of a specific order by ID.

openbroker order-status --oid 123456789   # By order ID
openbroker order-status --oid 0x1234...   # By client order ID

Flag	Description	Default
--oid	Order ID (number) or client order ID (hex string)	required

fees — Fee Schedule

View your fee tier, maker/taker rates, discounts, and recent daily trading volumes.

openbroker fees

candles — OHLCV Candle Data

View candlestick chart data for an asset.

openbroker candles --coin ETH                           # 24 hourly candles
openbroker candles --coin BTC --interval 4h --bars 48   # 48 four-hour bars
openbroker candles --coin SOL --interval 1d --bars 30   # 30 daily bars

Flag	Description	Default
--coin	Asset symbol	required
--interval	Candle interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M	1h
--bars	Number of bars to fetch	24

funding-history — Historical Funding Rates

View historical funding rate data for an asset.

openbroker funding-history --coin ETH              # Last 24h
openbroker funding-history --coin BTC --hours 168  # Last 7 days

Flag	Description	Default
--coin	Asset symbol	required
--hours	Hours of history to fetch	24

trades — Recent Trades (Tape)

View recent trades for an asset with buy/sell volume breakdown.

openbroker trades --coin ETH              # Last 30 trades
openbroker trades --coin BTC --top 50     # Last 50 trades

Flag	Description	Default
--coin	Asset symbol	required
--top	Number of recent trades	30

rate-limit — API Rate Limit

Check your API rate limit usage and capacity.

openbroker rate-limit

---

Trading Commands

buy / sell / market — Market Orders

Execute market orders with slippage protection. buy and sell are shortcuts that set --side automatically.

openbroker buy --coin ETH --size 0.1
openbroker sell --coin BTC --size 0.01
openbroker buy --coin SOL --size 10 --slippage 100 --dry
openbroker buy --coin ETH --size 0.1 --verbose

Flag	Description	Default
--coin	Asset to trade (ETH, BTC, SOL, HYPE, etc.)	required
--side	Order direction: buy or sell (auto-set by buy/sell command)	required
--size	Order size in base asset	required
--slippage	Slippage tolerance in bps (basis points)	50 (0.5%)
--reduce	Reduce-only order (won't increase position)	false
--dry	Preview order details without executing	—
--verbose	Show full API request/response	—

limit — Limit Orders

Place a limit order at a specific price. Supports three time-in-force modes.

openbroker limit --coin ETH --side buy --size 1 --price 3000
openbroker limit --coin BTC --side sell --size 0.1 --price 100000 --tif ALO
openbroker limit --coin SOL --side buy --size 10 --price 150 --reduce

Flag	Description	Default
--coin	Asset to trade	required
--side	buy or sell	required
--size	Order size in base asset	required
--price	Limit price	required
--tif	Time in force: GTC (rest on book), IOC (fill or cancel), ALO (post-only, maker only)	GTC
--reduce	Reduce-only order	false
--dry	Preview without executing	—

trigger — Trigger Orders (Conditional TP/SL)

Place conditional orders that activate when price reaches a trigger level. Used for stop losses, take profits, and conditional entries.

# Take profit: sell HYPE when price rises to $40
openbroker trigger --coin HYPE --side sell --size 0.5 --trigger 40 --type tp

# Stop loss: sell HYPE when price drops to $30
openbroker trigger --coin HYPE --side sell --size 0.5 --trigger 30 --type sl

# Buy stop: buy BTC on breakout above $75k
openbroker trigger --coin BTC --side buy --size 0.01 --trigger 75000 --type sl --reduce false

Flag	Description	Default
--coin	Asset to trade	required
--side	Order side when triggered: buy or sell	required
--size	Order size in base asset	required
--trigger	Trigger price (order activates at this level)	required
--type	Order type: tp (take profit) or sl (stop loss)	required
--limit	Custom limit price when triggered (overrides auto-calculation)	auto
--slippage	Slippage for stop loss limit price in bps	100 (1%)
--reduce	Reduce-only order	true
--dry	Preview without placing	—
--verbose	Show debug output	—

Trigger behavior:

• TP: Limit price = trigger price (favorable fill)
• SL: Limit price = trigger ± slippage (ensures fill in fast markets)

tpsl — Set TP/SL on Existing Position

Attach take-profit and/or stop-loss trigger orders to an open position. Supports absolute prices, percentage offsets, and breakeven stops.

openbroker tpsl --coin HYPE --tp 40 --sl 30          # Absolute prices
openbroker tpsl --coin ETH --tp +10% --sl -5%        # Percentage from entry
openbroker tpsl --coin HYPE --tp +10% --sl entry      # Breakeven stop
openbroker tpsl --coin ETH --sl -5%                   # Stop loss only
openbroker tpsl --coin ETH --tp 4000 --sl 3500 --size 0.5  # Partial position

Flag	Description	Default
--coin	Asset with an open position	required
--tp	Take profit price: absolute (40), percentage (+10%), or entry	—
--sl	Stop loss price: absolute (30), percentage (-5%), or entry	—
--size	Size to protect (for partial TP/SL)	full position
--sl-slippage	Stop loss slippage buffer in bps	100 (1%)
--dry	Preview orders without placing	—
--verbose	Show debug output	—

Shows risk/reward ratio and potential profit/loss before placing.

cancel — Cancel Orders

openbroker cancel --all                    # Cancel all open orders
openbroker cancel --coin ETH               # Cancel all ETH orders
openbroker cancel --coin ETH --oid 123456  # Cancel specific order
openbroker cancel --all --dry              # Preview what would be cancelled

Flag	Description	Default
--coin	Cancel orders for a specific coin only	—
--oid	Cancel a specific order by ID	—
--all	Cancel all open orders	—
--dry	Show orders without cancelling	—

outcome-buy / outcome-sell / outcome-order — HIP-4 Outcome Orders

Buy or sell a YES/NO outcome token. Buying opens exposure to that side; selling reduces or closes that token balance. Market orders are IOC limits with slippage protection.

openbroker outcomes --query BTC
openbroker outcome-buy --outcome 123 --outcome-side yes --size 10 --dry
openbroker outcome-buy --outcome 123 --outcome-side no --size 5 --price 0.42
openbroker outcome-sell --outcome #1230 --size 10
openbroker outcome-order --outcome 123 --outcome-side yes --side buy --size 10

Flag	Description	Default
--outcome	Outcome id, #<encoding>, or +<encoding>	required
--outcome-side	yes, no, 0, or 1 when using a plain outcome id	yes
--side	buy or sell (auto-set by shortcuts)	required
--size	Size in outcome token units	required
--price	Limit price between 0 and 1 (omit for market IOC)	market
--tif	Time in force for limit orders: Gtc, Ioc, Alo	Gtc
--slippage	Slippage tolerance in bps for market orders	50
--sz-decimals	Override size decimals if metadata omits token decimals	metadata / 0
--dry	Preview without executing	—

---

Advanced Execution

twap — Native TWAP Order

Place a native Hyperliquid TWAP order. The exchange handles order slicing and execution timing server-side — returns immediately with a TWAP ID.

# Buy 1 ETH over 30 minutes
openbroker twap --coin ETH --side buy --size 1 --duration 30

# Sell 0.5 BTC over 2 hours without randomized timing
openbroker twap --coin BTC --side sell --size 0.5 --duration 120 --randomize false

# Preview order details
openbroker twap --coin ETH --side buy --size 2 --duration 60 --dry

Flag	Description	Default
--coin	Asset to trade	required
--side	buy or sell	required
--size	Total order size in base asset	required
--duration	Duration in minutes (5–1440)	required
--randomize	Randomize execution timing	true
--reduce-only	Reduce-only order	false
--leverage	Set leverage before placing	—
--dry	Show order details without placing	—
--verbose	Show debug output	—

twap-cancel — Cancel TWAP Order

Cancel a running native TWAP order by its TWAP ID.

openbroker twap-cancel --coin ETH --twap-id 77738308

Flag	Description	Default
--coin	Asset symbol	required
--twap-id	TWAP order ID to cancel	required

twap-status — TWAP Order Status

View TWAP order history and currently running TWAP orders.

openbroker twap-status              # All TWAP history
openbroker twap-status --active     # Only running TWAPs

Flag	Description	Default
--active	Show only active/running TWAP orders	—

scale — Scale In/Out

Place a grid of limit orders to scale into or out of a position. Three distribution modes control how size is allocated across price levels. The ladder is submitted as a bulk order; if any level fails while others rest, the CLI cancels the resting ladder orders to avoid leaving an accidental partial grid.

openbroker scale --coin ETH --side buy --size 1 --levels 5 --range 2
openbroker scale --coin ETH --side buy --size 2 --levels 8 --range 5 --distribution exponential
openbroker scale --coin BTC --side sell --size 0.5 --levels 4 --range 3 --reduce

Flag	Description	Default
--coin	Asset to trade	required
--side	buy or sell	required
--size	Total order size in base asset	required
--levels	Number of price levels (orders)	required
--range	Price range from current mid in %	required
--distribution	Size distribution: linear (more at better prices), exponential (much more), flat (equal)	linear
--tif	Time in force: GTC or ALO	GTC
--reduce	Reduce-only orders (for scaling out)	false
--dry	Show order grid without placing	—
--verbose	Show debug output	—

bracket — Bracket Order (Entry + TP + SL)

Complete trade setup in one command. Supports market or limit entry with linked take-profit and stop-loss trigger orders. Limit entries wait for fill confirmation before arming TP/SL; if the wait times out, the entry can remain resting without unfilled protection orders.

openbroker bracket --coin ETH --side buy --size 0.5 --tp 3 --sl 1.5
openbroker bracket --coin BTC --side sell --size 0.1 --entry limit --price 100000 --tp 5 --sl 2

Flag	Description	Default
--coin	Asset to trade	required
--side	Entry direction: buy (long) or sell (short)	required
--size	Position size in base asset	required
--tp	Take profit distance in % from entry	required
--sl	Stop loss distance in % from entry	required
--entry	Entry type: market or limit	market
--price	Entry price (required if --entry limit)	—
--slippage	Slippage for market entry in bps	50
--entry-timeout	Seconds to wait for limit-entry fill confirmation before returning	300
--sl-slippage	Stop-loss trigger limit slippage in bps	100
--dry	Show bracket plan without executing	—
--verbose	Show debug output	—

Executes in 2 steps: Entry → linked TP/SL trigger pair. Market entries use the exchange response for fill size; limit entries use the user fills stream with REST fallback to confirm filled size before protection is armed.

chase — Chase Order

Follow the price with ALO (post-only) limit orders to get maker fills and avoid taker fees.

openbroker chase --coin ETH --side buy --size 0.5
openbroker chase --coin SOL --side buy --size 10 --offset 1 --timeout 60 --max-chase 50
openbroker chase --coin BTC --side sell --size 0.1 --offset 2 --timeout 600

Flag	Description	Default
--coin	Asset to trade	required
--side	buy or sell	required
--size	Order size in base asset	required
--offset	Offset from mid price in bps	5 (0.05%)
--timeout	Max time to chase in seconds	300 (5 min)
--interval	Price check / order update interval in ms	2000
--max-chase	Max price to chase to in bps from start	100 (1%)
--reduce	Reduce-only order	—
--dry	Show chase parameters without executing	—
--verbose	Show debug output	—

Uses ALO orders exclusively, guaranteeing maker rebates. Fill progress is tracked from user fill events with REST fallback, so partial fills reduce the next requote size. Stops when filled, timed out, or max chase reached.

---

Strategies

funding-arb — Funding Arbitrage

Collect funding payments by taking positions opposite to the majority. Monitors funding continuously and auto-closes when rates drop.

openbroker funding-arb --coin ETH --size 5000 --min-funding 25
openbroker funding-arb --coin BTC --size 10000 --duration 24 --check 30
openbroker funding-arb --coin ETH --size 5000 --dry

Flag	Description	Default
--coin	Asset to trade	required
--size	Position size in USD notional	required
--min-funding	Minimum annualized funding rate to enter (%)	20
--max-funding	Maximum rate — avoid extreme/squeeze risk (%)	200
--duration	How long to run in hours	∞
--check	Funding check interval in minutes	60
--close-at	Close position when funding drops below X%	5
--mode	perp (directional) or hedge (delta neutral — not yet implemented)	perp
--dry	Show opportunity analysis without trading	—
--verbose	Show debug output	—

Note: Hyperliquid funding is paid hourly (not 8h like CEXs). Annualized = hourly × 8,760.

grid — Grid Trading

Automatically buy low and sell high within a price range. Replaces filled orders on the opposite side.

openbroker grid --coin ETH --lower 3000 --upper 4000 --grids 10 --size 0.1
openbroker grid --coin BTC --lower 90000 --upper 100000 --grids 5 --size 0.01 --mode long

Flag	Description	Default
--coin	Asset to trade	required
--lower	Lower bound of grid (price)	required
--upper	Upper bound of grid (price)	required
--grids	Number of grid levels	10
--size	Size per grid level in base asset	—
--total-size	OR total size to distribute across grids	—
--mode	neutral (buy+sell), long (buys only), short (sells only)	neutral
--refresh	Rebalance check interval in seconds	60
--duration	How long to run in hours	∞
--dry	Show grid plan without placing orders	—
--verbose	Show debug output	—

Handles graceful shutdown (Ctrl+C) — cancels all grid orders and prints PnL summary.

dca — Dollar Cost Averaging

Accumulate a position over time with regular purchases at fixed USD amounts.

openbroker dca --coin ETH --amount 100 --interval 1h --count 24
openbroker dca --coin BTC --total 5000 --interval 1d --count 30

Flag	Description	Default
--coin	Asset to accumulate	required
--amount	USD amount per purchase	—
--total	OR total USD to invest (calculates per-purchase)	—
--interval	Time between purchases: Xm, Xh, Xd, Xw	required
--count	Number of purchases to make	required
--slippage	Slippage tolerance in bps	50
--dry	Show DCA plan and schedule without executing	—
--verbose	Show debug output	—

Reports running average price, total acquired, and unrealized PnL after completion.

mm-maker — Market Making (ALO / Maker-Only)

Provide liquidity using ALO (Add Liquidity Only) orders that are rejected if they would cross the spread. Guarantees you always earn the maker rebate (~0.3 bps). Reads the actual order book for pricing.

openbroker mm-maker --coin HYPE --size 1 --offset 1
openbroker mm-maker --coin ETH --size 0.1 --offset 2 --max-position 0.5

Flag	Description	Default
--coin	Asset to market make	required
--size	Order size on each side (base asset)	required
--offset	Offset from best bid/ask in bps	1
--max-position	Max net position before stopping that side	3× size
--skew-factor	How aggressively to skew for inventory	2.0
--refresh	Refresh interval in milliseconds	2000
--duration	How long to run in minutes	∞
--dry	Show setup without trading	—
--verbose	Show debug output	—

Fee structure: Taker ~2.5 bps (you pay), Maker ~0.3 bps (you earn). ALO-only = always earn.

mm-spread — Market Making (Spread-Based)

Place bid/ask quotes around the mid price, earning the spread when both sides fill. Includes inventory skewing and cooldown after fills.

openbroker mm-spread --coin ETH --size 0.1 --spread 10
openbroker mm-spread --coin BTC --size 0.01 --spread 5 --max-position 0.03 --cooldown 3000

Flag	Description	Default
--coin	Asset to market make	required
--size	Order size on each side (base asset)	required
--spread	Total spread width in bps from mid	required
--skew-factor	How aggressively to skew for inventory	2.0
--max-position	Maximum net position	3× size
--cooldown	Cooldown after fill before same-side requote (ms)	5000
--refresh	Refresh interval in milliseconds	2000
--duration	How long to run in minutes	∞
--dry	Show strategy parameters without trading	—
--verbose	Show debug output	—

Inventory management: When LONG → bid wider, ask tighter. When SHORT → bid tighter, ask wider. At max position → stops quoting that side.

---

Global Options

Flag	Description
--help, -h	Show help for a command
--dry	Preview without executing (all trading/strategy commands)
--verbose	Show debug output including API requests/responses
--version, -v	Print the CLI version

Safety

Always use --dry first to preview any operation:

openbroker buy --coin ETH --size 0.1 --dry

Use testnet for testing:

export HYPERLIQUID_NETWORK="testnet"

Configuration

Config is loaded from these locations (in order of priority):

1. Environment variables
2. .env file in current directory
3. ~/.openbroker/.env (global config)

Run openbroker setup to create the global config, or set environment variables:

export HYPERLIQUID_PRIVATE_KEY=0x...     # Required: wallet private key
export HYPERLIQUID_NETWORK=mainnet       # Optional: mainnet (default) or testnet
export HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Optional: for API wallets

API Wallet Setup (Recommended for Agents)

The safest default for agents delegates trading from an API wallet that cannot withdraw. The CLI prints an approval URL, waits for the funded master wallet to authorize it, and then saves the master account mapping automatically:

openbroker setup --api-wallet

Open the printed https://openbroker.dev/approve?agent=... link, connect the intended master Hyperliquid wallet, and approve ApproveAgent plus the 1 bps ApproveBuilderFee transaction. If approval times out, rerun the same command; OpenBroker resumes the incomplete setup without generating a new key.

Fresh Wallet Setup (Alternative)

Run interactive setup and explicitly choose option 1 to create a separately funded wallet:

openbroker setup

Builder Fee

Open Broker charges 1 bps (0.01%) per trade to fund development. The builder fee is automatically approved during openbroker setup.

openbroker approve-builder --check       # Check approval status
openbroker approve-builder               # Retry approval if needed
openbroker approve-builder --max-fee "0.05%"  # Custom max fee

Flag	Description	Default
--check	Only check current approval status, don't approve	—
--max-fee	Maximum fee rate to approve	0.1%
--builder	Custom builder address (advanced)	Open Broker
--verbose	Show debug output	—

Automation Runtime

Run audited TypeScript automations with required runtime guardrails:

openbroker auto run ./my-automation.ts --id my-auto --set coin=HYPE

WebSocket mode is enabled by default. Before an automation's onStart hooks run, OpenBroker subscribes to live mids, all-dex asset contexts, all-dex account state, spot balances, per-dex open-order snapshots, order updates, fills, and user events. L2 books are subscribed lazily per requested coin.

Existing strategies continue to use api.client. Inside the automation runtime, getAllMids(), getMetaAndAssetCtxs(), getUserState(), getUserStateAll(), getSpotBalances(), getOpenOrders(), and getL2Book() read the live WebSocket cache first and automatically fall back to REST when the socket is unavailable or a feed has not seeded. getPredictedFundings() has no socket equivalent, so it is request-de-duplicated, cached for 60 seconds, and serves the last successful value through transient rate limits.

api.every(intervalMs, handler) uses an independent scheduler and does not trigger a REST snapshot. --poll controls the disconnected REST fallback cadence; while WebSocket is healthy, full REST reconciliation runs no more than once per minute even when an older launch command passes a shorter value such as --poll 5000. Use --no-ws only when you intentionally need REST-only behavior.

Every automation must export guardrails plus its default factory. See SKILL.md for the complete schema, WebSocket event model, and runtime enforcement rules.

OpenClaw Plugin

OpenBroker ships as an OpenClaw plugin. When installed via OpenClaw, it registers structured agent tools and a background position watcher — no Bash wrappers needed.

Install via OpenClaw

openclaw plugins install openbroker

Or install from a local checkout during development:

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_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, OI)
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 markets and outcome token balances
Info	ob_rate_limit	API rate limit usage and capacity
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
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/status
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:

{
  "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:

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:

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

Development

For local development without global install:

git clone https://github.com/monemetrics/openbroker.git
cd openbroker
npm install
npx tsx scripts/info/account.ts

License

MIT