Perps (Hyperliquid)¶

Use Bullpen CLI for the Perps (Hyperliquid) product area: inspect accounts, preview perp trades, trade spot, use HIP-3 DEXes, run Pear pair trades, and manage Hyperliquid copy-trading subscriptions.

Start with a read-only account check. Submit a live command only after a preview or dry-run shows the expected account, DEX, market, size, and risk settings.

First Commands¶

Enable the Hyperliquid namespace:

bullpen experimental enable hyperliquid

Enable live Hyperliquid trading commands:

bullpen experimental enable hyperliquid_trading

Check the active account:

bullpen hl status --output json
bullpen hl balances --output json
bullpen hl orders --output json

The hl alias is equivalent to hyperliquid:

bullpen hl markets
bullpen hyperliquid markets

Example account-check output shape

{
  "address": "0x1111111111111111111111111111111111111111",
  "signer_address": "0x1111111111111111111111111111111111111111",
  "positions": [],
  "margin_summary": {
    "accountValue": "55.52",
    "totalNtlPos": "0",
    "totalMarginUsed": "0",
    "withdrawable": "55.52"
  }
}

Choose A Workflow¶

Goal	Guide	First safe command
Place a first Perps trade	Perps First Trade	`bullpen hl status --output json`
Trade selected-DEX HIP-3 markets such as TradeXYZ	HIP-3 Perps Trading	`bullpen hl perp-dexes --output json`
Trade spot pairs	Spot (Hyperliquid)	`bullpen hl spot pairs --output json`
Open or manage Pear pair trades	Pear Pair Trading	`bullpen hl pair status --output json`
Copy a Perps leader	Perps Copy Trading	`bullpen hl copy list --output json`
Diagnose balances, orders, deposits, or account routing	Hyperliquid Account Diagnostics	`bullpen hl balances --output json`
Compare Prediction and Perps copy trading	Copy Trading Boundaries	`bullpen tracker copy list --output json` and `bullpen hl copy list --output json`

Use the generated Hyperliquid command reference for exact flags, aliases, examples, and JSON-output contracts.

What Is Supported Now¶

Area	Supported CLI surface	Start here
Perps reads	Markets, mids, price, orderbook, funding, candles, status, balances, fills, order history, open orders, frontend orders, stats, topology, vault equity reads	`hl status`
Perps trades	`long`, `short`, `scale`, `stop-entry`, `close`, `close-all`, `modify`, leverage, margin updates, cancels, schedule cancel, TWAP, TP/SL	Perps First Trade
HIP-3	DEX discovery, selected-DEX public market reads, single-DEX `orders` / `frontend-orders`, all-DEX status/balances/orders, and DEX-qualified signed mutations for supported perp commands	HIP-3 Perps Trading
Spot	Spot metadata, pair discovery, orderbook, orders, order status/history, fills, IOC buy/sell, spot scale, cancel, cancel-all, spot TWAP create/cancel. Refresh orderbook/preview before IOC submits, verify a fill before cleanup sells, and use cancel-all only when you intend to clear every matching open spot order.	Spot (Hyperliquid)
Pear	Setup, session status/login/logout, positions, orders, TWAPs, pair open/close, close-all, cancel, TWAP cancel, risk update/clear, leverage update	Pear Pair Trading
Copy trading	Experimental create/reactivate, update, pause, resume, stop, pending confirm/reject, risk config, stats, leader profile, open-position reads. Use preview first and keep final live-cleanup proof in your automation logs.	Perps Copy Trading
Account movement	Deposit dry-run/live bridge path, transfer dry-run/live, withdraw dry-run/live, same-Hyperliquid send, subaccount reads and transfer, unified-account migration	Hyperliquid Account Diagnostics
Agent wallets	Direct Hyperliquid approve/revoke/list with slot and overwrite guards. Backend-managed agent registry lifecycle is still a product-contract boundary.	`hl agent`

Preview Before Live Submit¶

Trade commands use --preview. Movement commands use --dry-run. Both modes return before signing and submission. Preview does not sign, submit to Hyperliquid, or place an order.

bullpen hl long BTC --notional 100 --preview
bullpen hl short BTC --notional 100 --preview
bullpen hl stop-entry BTC --side long --trigger-price 70000 --notional 100 --preview
bullpen hl close BTC --preview
bullpen hl transfer --amount 10 --to perp --dry-run --output json
bullpen hl deposit --amount 10 --dry-run --output json

Live submit requires explicit confirmation:

bullpen hl long BTC --notional 100 --leverage 2 --yes

--non-interactive does not approve money movement. It suppresses prompts only. Use --yes when you intentionally want to submit.

Example no-submit trade preview

{
  "schema_version": 1,
  "kind": "hyperliquid_mutation_preview",
  "action": "long",
  "account": "0x1111111111111111111111111111111111111111",
  "coin": "BTC",
  "would_submit": false,
  "signature_requested": false,
  "exchange_request_submitted": false,
  "intent": {
    "side": "buy",
    "notional_usd": "25",
    "leverage": 2,
    "order_type": "market"
  }
}

HIP-3 DEXes¶

HIP-3 markets can share symbols with main-DEX markets. Keep DEX scope explicit and start with DEX discovery:

bullpen hl perp-dexes --output json
bullpen hl markets --dex <DEX> --output json
bullpen hl long <DEX>:<SYMBOL> --notional 10 --preview --output json

Use HIP-3 Perps Trading for the full selected-DEX workflow, including --dex, <DEX>:<SYMBOL> instruments, perp_dex / instrument_id output fields, and cleanup checks.

HIP-3 risk: HIP-3 DEXes are deployed and operated by third-party builders, not by the Hyperliquid core team. They can have thinner liquidity, wider spreads, and separate operational risk from main-DEX markets. Preview every order and keep DEX scope explicit.

Pear Pair Trading¶

Pear commands live under bullpen hl pair. They are not aliases for ordinary hl long, hl short, or hl close. Start with read-only setup state and a preview:

bullpen hl pair status --output json
bullpen hl pair setup --preview --output json
bullpen hl pair open --long BTC=0.5 --short ETH=0.5 --size-usd 22 --preview --output json

Use Pear Pair Trading for setup, open, risk update, leverage update, close, cancel, and cleanup proof. The Pear guide also explains the dedicated pear-pair-trade agent wallet and why ordinary Hyperliquid trade commands are not equivalent.

Perps Copy Trading¶

Hyperliquid copy trading lives under bullpen hl copy. Polymarket copy trading lives under bullpen tracker copy; do not mix the command families. Start with state reads, then preview before changing subscription state:

bullpen hl copy list --include-stopped --output json
bullpen hl copy risk config --output json
bullpen hl copy start <LEADER> --fixed-notional 10 --max-notional-per-order 15 --daily-notional-limit 100 --preview --output json

Use Perps Copy Trading for create/update, risk config, manual confirmations, pause/resume/stop, and cleanup proof. Use Copy Trading Boundaries when you need to choose between tracker copy and hl copy.

<LEADER> can be a Hyperliquid wallet address or a Bullpen username when Bullpen can resolve the username to a selected Arbitrum wallet.

Account And Funds Diagnostics¶

Use diagnostics before changing account state. The first three commands catch most balance, position, and open-order surprises:

bullpen hl status --output json
bullpen hl balances --output json
bullpen hl orders --output json

For account movement, dry-run first:

bullpen hl deposit --amount 10 --dry-run --output json
bullpen hl transfer --amount 10 --to perp --dry-run --output json
bullpen hl withdraw --amount 10 0x1111111111111111111111111111111111111111 --dry-run --output json

Withdraw safety: hl withdraw defaults to your own signer address. A live withdrawal to any other address requires --unsafe-recipient, and known centralized-exchange deposit addresses are blocked because Hyperliquid withdrawals settle on Arbitrum and an exchange may not credit them. Always --dry-run first and confirm the destination.

Use Hyperliquid Account Diagnostics for funded-vs-empty examples, public --address reads, HIP-3 all-DEX captures, agent-slot inspection, and deposit dry-run output.

Current Limits¶

The CLI exposes broad Hyperliquid coverage, but some surfaces remain contract-, safety-, or upstream-limited.

Limit	Current handling
Pear post-open rebalance, single-position detail, and richer watch flows	Pre-submit `pair open --rebalance`, risk edits, and leverage edits are supported. Post-open rebalance/detail/watch commands are not exposed until Pear API contracts are stable enough for preview and live safety checks.
Spot modify	Not exposed in this release line. Use supported spot buy/sell/scale, spot orders, spot order-status, cancel, cancel-all, and spot TWAP flows.
Spot resting, scale, cancel, and cancel-all cleanup support	Implemented with spot asset IDs and cleanup safeguards. For live cleanup, verify the target order first or intentionally use cancel-all for the selected pair.
Hyperliquid agent backend registry lifecycle	`hl agent approve` / `revoke` manage Hyperliquid `extraAgents` directly, and `hl agent list` reconciles that state against Bullpen-managed agent records. Creating or adopting arbitrary externally approved agents into Bullpen-managed agent records remains blocked on a backend/product contract.
Unit/Hyperunit external flows	Not public.
Managed API-wallet slot management	Not exposed as `hl api-wallet`; normal trades sign with the active EVM master wallet.
Routing-recovery signing and multisig wrappers	Not public. These require product, protocol, and support workflow approval.
Broad builder overrides	Debug-only and env-gated where present. Do not document or rely on them for normal trading.
Signed all-DEX fanout writes	Not exposed without an upstream write contract that preserves DEX identity and safety.
Vault/HLP write management	Read-only in this release line.

Troubleshooting¶

Symptom	First command
`Experimental feature not enabled`	`bullpen experimental enable hyperliquid`
Live trade command refuses before signing	Confirm `bullpen experimental enable hyperliquid_trading`, then rerun the same command with `--preview --output json`.
Wrong account appears in output	`bullpen wallet show-addresses --output json` and `bullpen hl status --output json`
HIP-3 symbol is unknown	`bullpen hl perp-dexes --output json`, then use `--dex <DEX>` or `<DEX>:<SYMBOL>`.
Requested leverage is above the market maximum	JSON errors use `HYPERLIQUID_LEVERAGE_EXCEEDS_MAX` with `requested_leverage`, `max_leverage`, `coin`, `instrument_id`, and `perp_dex` when inferable. Lower leverage to `max_leverage` and rerun with `--preview --output json`.
Copy subscription state is unclear	`bullpen hl copy show <SUBSCRIPTION_ID> --output json` and `bullpen hl copy executions --subscription <SUBSCRIPTION_ID> --output json`
Pear setup is unclear	`bullpen hl pair status --output json` and `bullpen hl pair setup --preview --output json`
Spot IOC order did not fill	`bullpen hl spot orderbook --pair <PAIR> --output json`, then rerun the spot buy/sell with `--preview --output json` before another live submit
Deposit, withdraw, or transfer routing is unclear	Use the matching `--dry-run --output json` command and read `source_wallet`, `destination`, `amount_usdc`, and `warnings`.