Hyperliquid¶

Bullpen ships a hyperliquid namespace for market data, account reads, core trade execution, trigger-aware order entry, and order-management actions.

This page documents the current public CLI surface only. It does not describe internal Hyperliquid helpers or trading flows that are present in bullpen-core but not exposed as public CLI commands in this release.

Availability¶

Hyperliquid support has two separate gates:

The binary must be built with the Cargo feature:

cargo build --features hyperliquid

Runtime experimental flags must be enabled in your config:

bullpen experimental enable hyperliquid

Mutating Hyperliquid commands additionally require:

bullpen experimental enable hyperliquid_trading

Rollout status: Bullpen now exposes practical CLI parity for the core Hyperliquid workflow, including public take-profit / stop-loss entry. Hyperliquid still remains experimental while broader rollout hardening and richer live UX stay in follow-up work.

The hl alias is also available:

bullpen hl markets

Multi-wallet Awareness¶

Hyperliquid uses your active EVM wallet as the signing address for authenticated account reads and all money-moving commands. Changing it with bullpen wallet select --chain evm <owner> changes which Hyperliquid account future commands use.

When an authenticated account read uses the default active account, table output can show:

Signing as: 0x1234... ("Main")

Signed account reports can also show a different query target when a signed read path targets another account:

Reading as: 0xabcd... (address override)

Structured JSON for hl status, hl balances, hl stats, and hl topology includes optional signer_address only for authenticated default-account reads. Explicit public reads with --address <ADDR> omit signer_address, do not require login, and do not render Signing as: / Reading as: context. Table-mode commands warn on stderr when multiple EVM wallets are available; use --no-multi-wallet-warning to suppress that warning. JSON output suppresses it automatically.

Read-Only Commands¶

These commands require the hyperliquid experimental flag.

Markets¶

List perpetual markets and live market context:

bullpen hl markets

Mids¶

Show current mid prices for active markets:

bullpen hl mids

Price¶

Show mark price, funding rate, open interest, and 24h volume for a single market:

bullpen hl price BTC
bullpen hl price ETH --output json

Returns the mark price, current funding rate, open interest, and 24-hour trading volume for the given coin. Use --output json for structured output.

Status¶

Show positions and margin state for an address:

bullpen hl status
bullpen hl status --address 0x1234...
bullpen hl status --output json

Default table output shows the active signing context before the queried account:

Hyperliquid Positions
Signing as: 0x1234... ("Main")
Address: 0x1234...

JSON output for the authenticated default account includes optional signer_address. Explicit --address public reads omit it.

Balances¶

Show spot balances plus a perp/spot equity breakdown:

bullpen hl balances
bullpen hl balances --address 0x1234...

If --address is omitted, Bullpen uses the active EVM wallet from bullpen login / bullpen wallet select. Use topology to discover owned subaccount and vault addresses, then pass the target address explicitly with --address. Default table output shows Signing as: 0x... ("label"); JSON output for the authenticated default account includes optional signer_address. Explicit --address public reads omit it.

Spot Estimated Value and Estimated Total Equity are intentionally estimated fields. If Hyperliquid does not return a usable spot mark price for a held asset, Bullpen warns that the estimated totals exclude that balance.

Fees¶

Show current fee rates, the published fee schedule tiers, and recent daily volume:

bullpen hl fees
bullpen hl fees --address 0x1234...

If --address is omitted, Bullpen uses the active EVM wallet from bullpen login / bullpen wallet select. Use topology to discover owned subaccount and vault addresses, then pass the target address explicitly with --address.

Stats¶

Show stable account stats from Hyperliquid portfolio history plus recent daily volume:

bullpen hl stats
bullpen hl stats --address 0x1234...

If --address is omitted, Bullpen uses the active EVM wallet from bullpen login / bullpen wallet select. Use topology to discover owned subaccount and vault addresses, then pass the target address explicitly with --address. JSON output for the authenticated default account includes optional signer_address. Explicit --address public reads omit it.

Topology¶

Show account topology for an address, including role metadata, vault equities, subaccounts, and extra agents:

bullpen hl topology
bullpen hl topology --address 0x1234...

If --address is omitted, Bullpen uses the active EVM wallet from bullpen login / bullpen wallet select. Use this command to discover owned subaccount and vault addresses before targeting them elsewhere in the CLI. JSON output for the authenticated default account includes optional signer_address. Explicit --address public reads omit it.

Orderbook¶

Show the L2 orderbook for a market:

bullpen hl orderbook ETH

Funding¶

funding has two modes:

No address or time window: show the current funding snapshot across markets.
Address and/or time window provided: show user funding payments.

Current funding snapshot:

bullpen hl funding

User funding history:

bullpen hl funding --address 0x1234...
bullpen hl funding --start 1713300000000 --end 1713900000000

If --address is omitted for user funding mode, Bullpen uses the active EVM wallet from bullpen login / bullpen wallet select.

Funding History¶

Show historical funding rates for a single market:

bullpen hl funding-history BTC
bullpen hl funding-history BTC --start 1713300000000 --end 1713900000000

Candles¶

Show OHLCV candles for a market:

bullpen hl candles BTC
bullpen hl candles BTC --interval 15m
bullpen hl candles BTC --start 1713300000000 --end 1713900000000

Supported intervals:

1m
5m
15m
1h
4h
1d

Orders¶

Show open orders for an address:

bullpen hl orders --address 0x1234...

This is the simpler open-orders view. Use frontend-orders when you need trigger, TP/SL-child, or nested frontend order detail.

Frontend Orders¶

Show rich frontend open orders, including trigger and child-order state:

bullpen hl frontend-orders
bullpen hl frontend-orders --address 0x1234...
bullpen hl frontend-orders --address 0x1234... --dex hl-main

Defaults to the active EVM wallet; use --address <ADDR> to query a different address.

Order Status¶

Show the current status for one order by numeric OID or client order ID:

bullpen hl order-status --oid 123456
bullpen hl order-status --cloid 0x00112233445566778899aabbccddeeff
bullpen hl order-status --address 0x1234... --oid 123456

Pass exactly one of --oid or --cloid. Defaults to the active EVM wallet; use --address <ADDR> to query a different address.

Order History¶

Show historical orders for an address, including the latest status timestamp:

bullpen hl order-history
bullpen hl order-history --address 0x1234...

Defaults to the active EVM wallet; use --address <ADDR> to query a different address.

Live Watch¶

watch streams line-oriented Hyperliquid websocket updates until you press Ctrl-C. Pass --updates <N> when you want the command to exit automatically after N payload messages, which is useful for scripting and smoke tests.

User-scoped watch commands default to the active EVM wallet from bullpen login / bullpen wallet select when --address is omitted.

Watch Mids¶

bullpen hl watch mids
bullpen hl watch mids --updates 1

Watch BBO¶

bullpen hl watch bbo BTC
bullpen hl watch bbo ETH --updates 5

Watch Orderbook¶

bullpen hl watch orderbook BTC
bullpen hl watch orderbook BTC --n-sig-figs 5 --mantissa 2 --updates 5 --output json

orderbook streams live l2Book updates. JSON output uses the existing watch envelope with channel: "l2Book" and data.levels as bid/ask level arrays.

Watch Trades¶

bullpen hl watch trades ETH
bullpen hl watch trades BTC --updates 5 --max-wait 2s --output json

trades streams the live public trade tape for one market. JSON output uses channel: "trades" and data[] trade entries.

Watch Candles¶

bullpen hl watch candles BTC
bullpen hl watch candles ETH --interval 1m --updates 3 --output json

candles streams live candle updates for one market. The default interval is 1h; supported intervals are 1m, 5m, 15m, 1h, 4h, and 1d. JSON output uses channel: "candle" and the Hyperliquid candle fields t, T, s, i, o, c, h, l, v, and n.

Watch Orders¶

bullpen hl watch orders
bullpen hl watch orders --address 0x1234...

Watch Fills¶

bullpen hl watch fills
bullpen hl watch fills --aggregate-by-time --updates 10

Watch Events¶

bullpen hl watch events

events is the combined user-event stream. It can surface fills, funding events, liquidations, and non-user cancels from one subscription.

Watch Fundings¶

bullpen hl watch fundings

Watch Ledger¶

bullpen hl watch ledger

ledger streams non-funding account ledger changes such as account-class transfers and withdrawals.

Watch Active Asset Data¶

bullpen hl watch active-asset BTC
bullpen hl watch active-asset ETH --address 0x1234...

Mutating Commands¶

These commands require both runtime flags:

hyperliquid
hyperliquid_trading

They also require an authenticated Bullpen account because Bullpen signs Hyperliquid requests with the active EVM wallet.

Current safety rule:

Without scope flags, public Hyperliquid mutations target the active EVM wallet from bullpen login / bullpen wallet select.
--subaccount <ADDR> targets an owned subaccount explicitly.
--vault <ADDR> targets a vault explicitly.
--subaccount and --vault are mutually exclusive.
Hyperliquid still signs with the active EVM wallet even when a subaccount or vault context is targeted.
transfer and withdraw currently target the active EVM wallet only and do not accept --subaccount or --vault.

Trade Guardrails¶

Use --preview first to inspect the order that would be built. Preview does not sign, submit to Hyperliquid, or place an order.
long, short, and market-style close use the configured default_slippage_pct.
long and short use default_leverage when --leverage is omitted.
Market-style long, short, and close orders use Hyperliquid's FrontendMarket TIF internally for mini-app parity.
close-all submits one reduce-only order batch for every open position, or every position matching --coin, and does not accept --size.
Adding --limit switches long, short, and close to explicit limit orders. Limit orders default to Gtc; pass --tif alo for post-only maker orders or --tif ioc for immediate-or-cancel limit behavior. --tif requires --limit.
Adding --tp or --sl to long or short creates a single-submit grouped entry bracket. Accepted take-profit / stop-loss children are reduce-only trigger-market orders and Hyperliquid applies server-side OCO behavior to the accepted TP/SL children.
Long brackets require take-profit above the entry reference and stop-loss below it. Short brackets reverse those sides. With --limit, the limit price is the reference; otherwise the current mark is the reference.
Adding --limit to close-all switches the batch to GTC close legs at the current mark price; default close-all uses market-style IOC close legs with slippage-adjusted mark prices.
Hyperliquid rejects orders under $10 notional.
Requested leverage must be valid for the market and cannot exceed the market's max leverage.
If builder attribution is configured, long, short, and close may submit a one-time builder approval before the trade.
close-all uses one confirmation prompt, one builder-fee context, and one Hyperliquid order batch. It does not cancel resting, take-profit, or stop-loss orders; run bullpen hl cancel-all --yes separately when you need to clear open orders too.

Transfer¶

Transfer USDC between Hyperliquid spot and perp balances:

bullpen hl transfer --amount 25 --to perp --yes
bullpen hl transfer --amount 25 --to spot --yes

This flow currently targets the active EVM wallet's Hyperliquid account only.

Deposit¶

Bridge USDC from Arbitrum to your Hyperliquid Spot balance:

bullpen hl deposit --amount 25 --yes
bullpen hl deposit --amount 25 --dry-run
bullpen hl deposit --amount 25 --from arbitrum --yes

Hyperliquid minimum deposit is $5. Only USDC on Arbitrum is supported as the bridge source today. See hyperliquid/deposit for the full flag surface.

Withdraw¶

Withdraw USDC from Hyperliquid to the active EVM wallet:

bullpen hl withdraw --amount 10 --yes

This flow currently targets the active EVM wallet's Hyperliquid account only and withdraws to that wallet address.

Long¶

Open a long position using USD notional size:

bullpen hl long BTC --size 100 --preview
bullpen hl long BTC --size 100 --yes
bullpen hl long ETH --size 250 --leverage 7 --yes
bullpen hl long SOL --size 150 --limit 140 --yes
bullpen hl long BTC --size 100 --limit 60000 --tif alo --yes
bullpen hl long BTC --size 100 --tp 65000 --sl 59000 --preview
bullpen hl long BTC --size 100 --subaccount 0x2222... --yes

Omit --limit to submit a market-style order using the configured Hyperliquid slippage default. Limit orders default to --tif gtc; --tif alo is post-only and must be used with --limit.

--tp and --sl add grouped reduce-only trigger children to the entry. Use --preview first to inspect the bracket legs and risk/reward ratio without signing or submitting. Live submission uses one confirmation gate and one Hyperliquid normalTpsl order action. If Hyperliquid returns mixed per-leg statuses, the CLI exits non-zero after printing the report, preserves every leg in order_statuses, and records best-effort cleanup attempts in cancel_statuses.

Bracket preview JSON includes the planned child legs:

{
  "action": "long",
  "bracket_legs": [
    {"kind": "take-profit", "side": "sell", "trigger_px": "65000", "limit_px": "65000", "reduce_only": true},
    {"kind": "stop-loss", "side": "sell", "trigger_px": "59000", "limit_px": "59000", "reduce_only": true}
  ],
  "risk_reward": "1.25"
}

Short¶

Open a short position using USD notional size:

bullpen hl short BTC --size 100 --preview
bullpen hl short BTC --size 100 --yes
bullpen hl short ETH --size 250 --leverage 7 --yes
bullpen hl short SOL --size 150 --limit 140 --yes
bullpen hl short BTC --size 100 --limit 60000 --tif alo --yes
bullpen hl short BTC --size 100 --tp 59000 --sl 65000 --preview
bullpen hl short ETH --size 250 --vault 0x3333... --yes

short follows the same market-style, limit, TIF, slippage, leverage, builder-approval, and grouped-bracket rules as long.

Close¶

Close a position fully or partially:

bullpen hl close BTC --preview
bullpen hl close BTC --yes
bullpen hl close ETH --size 75 --yes
bullpen hl close BTC --limit 60000 --tif alo --yes
bullpen hl close BTC --subaccount 0x2222... --yes

Omit --size to close the full position. Omit --limit to submit a market-style reduce-only close using the configured slippage default. Add --limit for a resting reduce-only close; --tif alo is available for post-only maker closes and requires --limit. Market-style closes may trigger the one-time builder approval if builder attribution is enabled.

Close All¶

Flatten every open position with one batched reduce-only order action:

bullpen hl close-all --preview --output json
bullpen hl close-all --yes
bullpen hl close-all --coin ETH --preview
bullpen hl close-all --coin ETH --yes
bullpen hl close-all --limit --yes
bullpen hl close-all --subaccount 0x2222... --yes
bullpen hl close-all --vault 0x3333... --yes

Default close-all uses market-style IOC close legs with slippage-adjusted mark prices. --limit uses GTC close legs at the current mark price. The command always sets every leg reduce-only and has no partial-size mass-close mode. Use hl close <COIN> --size <USD> when you need to reduce one position by a smaller notional amount.

Preview mode plans the per-position breakdown without signing, consuming a nonce, approving builder context, or submitting to Hyperliquid. Live mode requires one confirmation for the whole plan unless --yes is present. JSON output includes close_all_positions, positions_flattened, positions_remaining_after_partial_fail, and total_notional_usd. Resting, waiting, rejected, missing, or partially filled legs count as remaining so automation can detect incomplete flattening.

close-all does not cancel resting orders, take-profit orders, or stop-loss orders. Use bullpen hl cancel-all --yes separately to clear open orders.

Take Profit¶

Place a reduce-only take-profit trigger for an existing position:

bullpen hl take-profit ETH --trigger-price 2600 --preview
bullpen hl take-profit ETH --trigger-price 2600 --size 0.25 --preview --output json
bullpen hl take-profit ETH --trigger-price 2600 --yes
bullpen hl take-profit ETH --trigger-price 2600 --size 0.25 --limit 2610 --yes
bullpen hl take-profit BTC --trigger-price 71000 --subaccount 0x2222... --yes

Omit --size to target the full current position. Omit --limit to submit a trigger-market exit; adding --limit turns it into a trigger-limit order. Use --preview first to check the reduce side, base-unit size, mark/entry prices, PnL at trigger, leveraged ROI, fee estimate, and wrong-side trigger validation without signing or submitting. --size is in base units for TP/SL, not USD notional.

Stop Loss¶

Place a reduce-only stop-loss trigger for an existing position:

bullpen hl stop-loss ETH --trigger-price 2300 --preview
bullpen hl stop-loss ETH --trigger-price 2300 --size 0.25 --preview --output json
bullpen hl stop-loss ETH --trigger-price 2300 --yes
bullpen hl stop-loss ETH --trigger-price 2300 --size 0.25 --limit 2295 --yes
bullpen hl stop-loss BTC --trigger-price 64000 --vault 0x3333... --yes

stop-loss follows the same full-position / partial-position and trigger-market / trigger-limit rules as take-profit. Use --preview to verify PnL, ROI, side-of-mark validation, and the base-unit size before signing.

Cancel¶

Cancel one resting order by numeric OID:

bullpen hl cancel 123456 --yes
bullpen hl cancel 123456 --vault 0x3333... --yes

If you only have a client order ID, use cancel-by-cloid.

Cancel All¶

Cancel all resting orders, optionally for one market:

bullpen hl cancel-all --yes
bullpen hl cancel-all ETH --yes

Leverage¶

Set leverage for a market:

bullpen hl leverage BTC 5 --yes
bullpen hl leverage ETH 8 --isolated --yes

Cross margin is the default. Use --isolated to set isolated leverage. The requested leverage must also be accepted by the target market.

Modify¶

Modify a resting order by numeric OID:

bullpen hl modify 123456 --price 2100
bullpen hl modify 123456 --size 0.5
bullpen hl modify 123456 --price 2100 --size 0.5 --yes

At least one of --price or --size is required. modify is intentionally limited to plain resting orders. If you need to change a trigger / TP-SL order, cancel it and recreate it with take-profit or stop-loss.

Cancel By Cloid¶

Cancel a resting order by client order ID:

bullpen hl cancel-by-cloid ETH 0x00112233445566778899aabbccddeeff --yes

Schedule Cancel¶

Set or clear a dead-man's-switch cancel-all time:

bullpen hl schedule-cancel --time 1713900000000 --yes
bullpen hl schedule-cancel --clear --yes

--time and --clear are mutually exclusive. You must pass exactly one of them; omitting both is not allowed.

Update Margin¶

Add or remove isolated margin for a position:

bullpen hl update-margin ETH --amount 50 --yes
bullpen hl update-margin ETH --amount -25 --yes

Positive amounts add isolated margin. Negative amounts remove isolated margin.

Output¶

Use the global --output flag on JSON-capable Hyperliquid commands:

bullpen --output json hl markets
bullpen --output json hl funding-history BTC

For watch commands, --output json emits one JSON object per websocket payload message.

Configuration¶

Bullpen resolves Hyperliquid settings from the same config file used for the rest of the CLI, including --config /path/to/config.toml.

Publicly documented keys:

[hyperliquid]
api_url = "https://api.hyperliquid.xyz"
ws_url = "wss://api.hyperliquid.xyz/ws"
builder_address = "0x1234..."
builder_fee_bps = 4.5
default_leverage = 5
default_slippage_pct = 1.0

Notes:

api_url is used by the current public Hyperliquid CLI commands.
ws_url is used by bullpen hl watch ... for the public live/watch surface.
builder_address and builder_fee_bps actively control builder attribution for long, short, and close.
default_leverage is used when long or short omit --leverage.
default_slippage_pct is used for market-style long, short, and close.
scope targeting is explicit flags only; Bullpen does not currently support persistent config defaults for subaccount or vault targeting.
expires_after remains an internal request-context knob. It is not a public CLI flag or documented config key in this release.

What Is Not Publicly Exposed Here¶

The public CLI page intentionally does not document commands that are not currently wired into bullpen hyperliquid.

Examples of functionality that may exist in shared core code or internal plans but is not part of the current public CLI surface include:

public expiry overrides for Hyperliquid request context
raw grouped trigger payload construction beyond the public take-profit / stop-loss entry points

Trigger / TP-SL placement is public now, but Bullpen still keeps the lifecycle deliberately narrow:

entry is exposed as take-profit and stop-loss
rich inspection is available through frontend-orders
modify does not support trigger orders; cancel and recreate them instead

That keeps the public contract explicit instead of implying that every lower-level grouped trigger shape is a stable CLI feature.

Troubleshooting¶

"Experimental feature not enabled"¶

Enable the runtime flags:

bullpen experimental enable hyperliquid
bullpen experimental enable hyperliquid_trading

"requires the 'hyperliquid' compile-time feature"¶

Your binary was built without Hyperliquid support. Rebuild with:

cargo build --features hyperliquid

"Not logged in"¶

Mutating commands need authenticated Bullpen credentials:

bullpen login

"invalid Hyperliquid API URL"¶

Check the [hyperliquid] block in the config file you are actually using:

bullpen --config /path/to/config.toml config show