Openbroker

openbroker search --query GOLD              # Find all GOLD markets across all providers
openbroker search --query oil               # Find oil-related assets (CL, BRENTOIL, USOIL...)
openbroker search --query BTC --type perp   # BTC perps only
openbroker search --query NATGAS --type hip3  # HIP-3 only

Or with the ob_search plugin tool: { "query": "gold" } or { "query": "oil", "type": "hip3" }

HIP-3 assets use dex:COIN format — e.g., xyz:CL not just CL. If you get an error like "No market data found", search for the asset to find the correct prefixed ticker. Common HIP-3 dexes: xyz, flx, km, hyna, vntl, cash.

Troubleshooting: CLI Fallback

If an ob_* plugin tool returns unexpected errors, empty results, or crashes, fall back to the equivalent CLI command via Bash. The CLI and plugin tools share the same core code, but the CLI has more mature error handling and output.

When to use CLI fallback:

• Plugin tool returns null, empty data, or throws an error
• You need data the plugin tool doesn't expose (e.g., --verbose debug output)
• Long-running operations (strategies) — the CLI handles timeouts and progress better

Add --dry to any trading CLI command to preview without executing. Add --json to info commands for structured output.

Command Reference

Setup

openbroker setup              # One-command setup (wallet + config + builder approval)
openbroker approve-builder --check  # Check builder fee status (for troubleshooting)

The setup command offers three modes:

1. Generate fresh wallet (recommended for agents) — creates a dedicated trading wallet with builder fee auto-approved. No browser steps needed — just fund with USDC and start trading.
2. Import existing key — use a private key you already have
3. Generate API wallet — creates a restricted wallet that can trade but cannot withdraw. Requires browser approval from a master wallet.

For options 1 and 2, setup saves config and approves the builder fee automatically. For option 3 (API wallet), see the API Wallet Setup section below.

Fresh Wallet Setup (Recommended for Agents)

The simplest setup for agents. A fresh wallet is generated, the builder fee is auto-approved, and the agent is ready to trade immediately after funding.

Flow:

1. Run openbroker setup and choose option 1 ("Generate a fresh wallet")
2. The CLI generates a wallet, saves the config, and approves the builder fee automatically
3. Fund the wallet by sending USDC from your Hyperliquid account to the agent's wallet address using the Send feature on https://app.hyperliquid.xyz/. Funding should be done on Hyperliquid L1 only.
4. Start trading

API Wallet Setup (Alternative)

API wallets can place trades on behalf of a master account but cannot withdraw funds. Use this if you prefer to keep funds in your existing wallet and only delegate trading access.

Flow:

1. Run openbroker setup and choose option 3 ("Generate API wallet")
2. The CLI generates a keypair and prints an approval URL (e.g. https://openbroker.dev/approve?agent=0xABC...)
3. The agent owner opens the URL in a browser and connects their master wallet (MetaMask etc.)
4. The master wallet signs two transactions: ApproveAgent (authorizes the API wallet) and ApproveBuilderFee (approves the 1 bps fee)
5. The CLI detects the approval automatically and saves the config

After setup, the config will contain:

HYPERLIQUID_PRIVATE_KEY=0x...        # API wallet private key
HYPERLIQUID_ACCOUNT_ADDRESS=0x...    # Master account address
HYPERLIQUID_NETWORK=mainnet

Important for agents: When using an API wallet, pass the approval URL to the agent owner (the human who controls the master wallet). The owner must approve in a browser before the agent can trade. The CLI waits up to 10 minutes for the approval. If it times out, re-run openbroker setup.

Account Info

openbroker account            # Balance, equity, margin
openbroker account --orders   # Include open orders
openbroker account --address 0xabc...  # Look up another account
openbroker positions          # Open positions with PnL
openbroker positions --coin ETH  # Specific coin
openbroker positions --address 0xabc...  # Another account's positions

Funding Rates

openbroker funding --top 20   # Top 20 by funding rate
openbroker funding --coin ETH # Specific coin

Markets

openbroker markets --top 30   # Top 30 main perps
openbroker markets --coin BTC # Specific coin

All Markets (Perps + Spot + HIP-3)

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

Search Markets (Find assets across providers)

openbroker search --query GOLD    # Find all GOLD markets
openbroker search --query BTC     # Find BTC across all providers
openbroker search --query ETH --type perp  # ETH perps only

Spot Markets

openbroker spot                   # Show all spot markets
openbroker spot --coin PURR       # Show PURR market info
openbroker spot --balances        # Show your spot balances
openbroker spot --balances --address 0xabc...  # Another account's spot balances
openbroker spot --top 20          # Top 20 by volume

Trade Fills

openbroker fills                          # Recent fills
openbroker fills --coin ETH               # ETH fills only
openbroker fills --coin BTC --side buy --top 50
openbroker fills --address 0xabc...       # Another account's fills

Order History

openbroker orders                         # Recent orders (all statuses)
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
openbroker orders --address 0xabc... --open  # Another account's open orders

Order Status

openbroker order-status --oid 123456789   # Check specific order
openbroker order-status --oid 0x1234...   # By client order ID
openbroker order-status --oid 123456789 --address 0xabc...  # On another account

Fee Schedule

openbroker fees                           # Fee tier, rates, and volume
openbroker fees --address 0xabc...        # Another account's fees

Candle Data (OHLCV)

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

Funding History

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

Recent Trades (Tape)

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

Rate Limit

openbroker rate-limit                     # API usage and capacity

Funding Rate Scanner (Cross-Dex)

openbroker funding-scan                          # Scan all dexes, >25% threshold
openbroker funding-scan --threshold 50 --pairs   # Show opposing funding pairs
openbroker funding-scan --hip3-only --top 20     # HIP-3 only
openbroker funding-scan --watch --interval 120   # Re-scan every 2 minutes

Trading Commands

HIP-3 Perp Trading

All trading commands support HIP-3 assets using dex:COIN syntax:

openbroker buy --coin xyz:CL --size 1              # Buy crude oil on xyz dex
openbroker sell --coin xyz:BRENTOIL --size 1        # Sell brent oil
openbroker limit --coin xyz:GOLD --side buy --size 0.1 --price 2500

Market Orders (Quick)

openbroker buy --coin ETH --size 0.1
openbroker sell --coin BTC --size 0.01
openbroker buy --coin SOL --size 5 --slippage 100  # Custom slippage (bps)

Market Orders (Full)

openbroker market --coin ETH --side buy --size 0.1
openbroker market --coin BTC --side sell --size 0.01 --slippage 100

Limit Orders

openbroker limit --coin ETH --side buy --size 1 --price 3000
openbroker limit --coin SOL --side sell --size 10 --price 200 --tif ALO

Set TP/SL on Existing Position

# Set take profit at $40, stop loss at $30
openbroker tpsl --coin HYPE --tp 40 --sl 30

# Set TP at +10% from entry, SL at entry (breakeven)
openbroker tpsl --coin HYPE --tp +10% --sl entry

# Set only stop loss at -5% from entry
openbroker tpsl --coin ETH --sl -5%

# Partial position TP/SL
openbroker tpsl --coin ETH --tp 4000 --sl 3500 --size 0.5

Trigger Orders (Standalone TP/SL)

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

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

Cancel Orders

openbroker cancel --all           # Cancel all orders
openbroker cancel --coin ETH      # Cancel ETH orders only
openbroker cancel --oid 123456    # Cancel specific order

Advanced Execution

TWAP (Native Exchange Order)

# Buy 1 ETH over 30 minutes (exchange handles slicing)
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

# Cancel a running TWAP
openbroker twap-cancel --coin ETH --twap-id 77738308

# Check TWAP status
openbroker twap-status --active

Scale In/Out (Grid Orders)

# Place 5 buy orders ranging 2% below current price
openbroker scale --coin ETH --side buy --size 1 --levels 5 --range 2

# Scale out with exponential distribution
openbroker scale --coin BTC --side sell --size 0.5 --levels 4 --range 3 --distribution exponential --reduce

Bracket Order (Entry + TP + SL)

# Long ETH with 3% take profit and 1.5% stop loss
openbroker bracket --coin ETH --side buy --size 0.5 --tp 3 --sl 1.5

# Short with limit entry
openbroker bracket --coin BTC --side sell --size 0.1 --entry limit --price 100000 --tp 5 --sl 2

Chase Order (Follow Price)

# Chase buy with ALO orders until filled
openbroker chase --coin ETH --side buy --size 0.5 --timeout 300

# Aggressive chase with tight offset
openbroker chase --coin SOL --side buy --size 10 --offset 2 --timeout 60

Order Types

Limit Orders vs Trigger Orders

Limit Orders (openbroker limit):

• Execute immediately if price is met
• Rest on the order book until filled or cancelled
• A limit sell BELOW current price fills immediately (taker)
• NOT suitable for stop losses

Trigger Orders (openbroker trigger, openbroker tpsl):

• Stay dormant until trigger price is reached
• Only activate when price hits the trigger level
• Proper way to set stop losses and take profits
• Won't fill prematurely

When to Use Each

Common Arguments

All commands support --dry for dry run (preview without executing).

Order Arguments

TP/SL Price Formats

Configuration

Config is loaded from (in priority order):

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

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.
• Automation tools (ob_auto_run, ob_auto_stop, ob_auto_list) — start, stop, and manage custom trading automations from within the agent.
• 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: