Skip to content

Spot (Hyperliquid)

Use this guide to inspect Hyperliquid spot markets, preview spot orders, and manage spot orders without confusing spot pairs with perp symbols. Hyperliquid spot trading remains experimental, and this page does not claim full spot parity with every web-app flow.

Start With Read-Only Spot State

Enable the Hyperliquid namespace before planning a trade.

State change: Enable Hyperliquid CLI reads.

bullpen experimental enable hyperliquid

Then list spot pairs:

bullpen hl spot-meta --output json
bullpen hl spot pairs --quote USDC --limit 20 --output json

Use search when you know the base token.

bullpen hl spot pairs --search hype --quote USDC --limit 20 --output json

These commands do not sign, submit orders, approve agents, or change account state.

Inspect Liquidity

Open the spot orderbook for the pair you plan to trade.

bullpen hl spot orderbook --pair HYPE/USDC --output json

Use the orderbook to choose a limit price before previewing an order. Spot --size is base-token size, not USD notional. For IOC orders, choose a price that can cross available resting liquidity. If the live command returns HYPERLIQUID_IOC_NO_MATCH, refresh the orderbook or preview, adjust the price, and submit only if the refreshed preview still matches your intent.

Check Existing Spot Orders

Read open spot orders before submitting or canceling anything.

bullpen hl spot orders --pair HYPE/USDC --output json

If support asks for a specific address, use an explicit read target.

bullpen hl spot orders --address 0x1111111111111111111111111111111111111111 --pair HYPE/USDC --output json

These reads filter rows through Hyperliquid spot metadata so same-symbol perp rows are not treated as spot orders.

Inspect one order by order ID when you need a specific order state.

bullpen hl spot order-status --pair HYPE/USDC --oid 123456789 --output json

Use history and fills for support capture or reconciliation.

bullpen hl spot order-history --pair HYPE/USDC --output json
bullpen hl spot fills --pair HYPE/USDC --start 1700000000000 --end 1700086400000 --output json

Enable Trading Explicitly

Live spot mutations require the trading flag. Enabling the flag does not submit an order by itself.

State change: Enable live Hyperliquid spot mutations after preview review.

bullpen experimental enable hyperliquid_trading

Preview Spot Buy And Sell Orders

Preview a buy before submitting. Preview mode resolves the pair and prints the planned order without signing or submitting.

bullpen hl spot buy --pair HYPE/USDC --price 25 --size 0.5 --tif ioc --preview --output json

Preview a sell the same way.

bullpen hl spot sell --pair HYPE/USDC --price 25 --size 0.5 --tif ioc --preview --output json

Review these fields before any live submit:

  • pair
  • asset_id
  • side
  • price
  • size
  • tif
  • fill_estimate.status
  • fill_estimate.expected_base_size
  • fill_estimate.expected_notional_usd
  • fill_estimate.estimated_avg_fill_px
  • fill_estimate.estimated_worst_fill_px
  • fill_estimate.estimated_slippage_bps
  • fill_estimate.estimated_taker_fee_usd
  • fill_estimate.fee_rate_source or fill_estimate.fee_unavailable_reason
  • fill_estimate.book_depth_consumed_levels
  • fill_estimate.insufficient_depth
  • fill_estimate.unavailable_reason
  • would_submit
  • signature_requested
  • exchange_request_submitted

For preview and other no-submit stops, those submit fields are false. For an uncertain live /exchange write, JSON instead shares request_attempted:true, submission_state:"outcome_unknown", requires_state_inspection:true, and retry booleans (safe_to_retry, retryable, retryable_without_action, auto_retried) set to false. Send uncertainty reports exchange_request_submitted:null and submitted:null because receipt is unknown. Response-body-read and successful-response-parse uncertainty report both fields as true because Hyperliquid returned an HTTP response, but the client cannot interpret the outcome. Inspect spot orders, fills, and balances before any manual retry.

Live spot buy and sell support ioc, gtc, and alo. Resting gtc and post-only alo orders can be reviewed with spot orders and cleaned up with spot cancel or spot cancel-all.

For ioc and gtc, preview attempts to estimate fill size, depth consumed, slippage, and taker fee from the visible spot orderbook and fee evidence. If fee evidence is unavailable, the preview can still report fill and depth fields with fee_unavailable_reason.

For alo, preview reports fill_estimate.status: "unavailable" because a post-only order should not take liquidity. If the order would not immediately cross, the reason explains that fill price, filled notional, fee, and slippage remain unavailable until a resting order executes. If it would cross visible depth, the reason explains that Hyperliquid may reject the post-only order instead of taking liquidity.

Submit Only After Review

Submit a live spot buy only after the preview matches the intended active account, pair, side, price, base-token size, and time-in-force.

bullpen hl spot buy --pair HYPE/USDC --price 25 --size 0.5 --tif ioc --preview --output json

Live: Run the matching spot buy preview above first. Submit only when the preview still matches the active account, pair, side, price, base-token size, and time-in-force.

bullpen hl spot buy --pair HYPE/USDC --price 25 --size 0.5 --tif ioc --yes --output json

Submit a live spot sell the same way.

bullpen hl spot sell --pair HYPE/USDC --price 25 --size 0.5 --tif ioc --preview --output json

Live: Run the matching spot sell preview above first. Submit only when the preview still matches the active account, pair, side, price, base-token size, and time-in-force.

bullpen hl spot sell --pair HYPE/USDC --price 25 --size 0.5 --tif ioc --yes --output json

If an IOC spot order returns HYPERLIQUID_IOC_NO_MATCH, the order did not immediately match and should not be treated as filled. Refresh bullpen hl spot orderbook --pair <PAIR> --output json, choose a marketable price, rerun --preview, and only then submit another live order. Do not run a cleanup sell unless the buy output, fills, or balance proves inventory exists.

Preview Cancellations

Preview a single cancel before signing. Use either an order ID or a client order ID.

bullpen hl spot cancel --pair HYPE/USDC --oid 123456789 --preview --output json

Preview a pair-scoped cancel-all before signing.

bullpen hl spot cancel-all --pair HYPE/USDC --preview --output json

Live cancel commands require --yes. A live cancel-all with no matching spot orders is a no-op with no signature or exchange request.

Preview Spot TWAP

Preview a spot TWAP before submitting. Spot TWAP sizing is base-token size, not USD notional.

bullpen hl spot twap create --pair HYPE/USDC --side buy --base-size 0.1 --minutes 15 --preview --output json

Preview canceling a running spot TWAP before signing.

bullpen hl spot twap cancel --pair HYPE/USDC 8801 --preview --output json

Live: Spot TWAP create and cancel can submit real Hyperliquid exchange actions. Submit only after the matching preview shows the intended pair, side, base-token size, duration, account scope, or TWAP id. Hyperliquid TWAP actions do not expose builder attribution, so preview and live reports disclose that TWAP submits without builder attribution.

Preview Spot Scale

Preview a spot ladder before submitting multiple levels. Spot scale uses base-token size, not USD notional, and resolves the official Hyperliquid spot asset id for each leg.

bullpen hl spot scale --pair HYPE/USDC --side buy --base-size 0.3 --start 24 --end 22 --levels 3 --tif gtc --preview --output json

Spot scale live submit requires --yes. The command uses spot asset IDs, deterministic client order IDs, no builder approval, no reduce-only flag, and no leverage update. If Hyperliquid returns a mixed, missing, or uncertain batch response, the CLI reports success=false and attempts best-effort cleanup of resting legs.

Boundaries

  • Hyperliquid spot trading remains experimental in this release.
  • Spot buy, sell, and scale submit from the active EVM master account.
  • Spot buy, sell, and scale do not expose scoped live submits in this release.
  • Spot TWAP supports subaccount and vault execution context, but Bullpen still signs with the active EVM master wallet.
  • For live cleanup, verify a single target order with spot order-status or preview first; use spot cancel-all only when you intentionally want to clear every matching open spot order.
  • For IOC cleanup, verify that the original buy filled before selling. A typed HYPERLIQUID_IOC_NO_MATCH response means there is no proven fill to clean up.
  • Spot previews expose fill/depth/slippage/fee evidence when available. Treat fill_estimate.status: "unavailable" and fill_estimate.unavailable_reason as a stop sign for fill assumptions, especially for post-only alo orders.
  • Spot modify and broad spot builder attribution are not exposed.
  • Hyperliquid copy trading is separate from spot trading and lives under bullpen hl copy; use the copy-trading guide before creating or changing a subscription.

Generated References

Use the generated references for exact options: spot-meta, spot pairs, spot orderbook, spot orders, spot order-status, spot order-history, spot fills, spot buy, spot sell, spot scale, spot cancel, spot cancel-all, spot TWAP create, and spot TWAP cancel.

For account-level diagnostics, use Hyperliquid Account Diagnostics. For the full public command surface and release boundaries, return to Perps (Hyperliquid).