Skip to content

HIP-3 Perps Trading Tutorial

HIP-3 markets are Hyperliquid perpetual markets that live under a named perp DEX, such as TradeXYZ. In Bullpen, you trade them through the same hl commands as main Hyperliquid perps, but you must keep the DEX scope explicit so orders, positions, and open-order reads do not collapse into the wrong market.

Use this tutorial to discover a HIP-3 DEX, inspect a market, preview a trade, submit only after review, and clean up exposure.

Before You Start

Enable Hyperliquid reads:

bullpen login
bullpen experimental enable hyperliquid

Enable live Hyperliquid trading only when you intend to submit orders:

bullpen experimental enable hyperliquid_trading

1. Discover DEXes And Markets

List registered HIP-3 perp DEXes:

bullpen hl perp-dexes --output json

Use the dex_id returned by perp-dexes for --dex. HIP-3 DEXes are third-party builder markets and can have thinner liquidity than main Hyperliquid perps, so inspect price, order book depth, and open orders before submitting. Registry commands such as perp-dexes, markets, and mids do not take a coin argument; scope them with --dex <DEX> when a DEX-specific flag is available. Use xyz:SPCX only on commands that accept a coin.

List markets for one DEX:

bullpen hl markets --dex xyz --output json

The HIP-3 registry changes over time. Use bullpen hl perp-dexes --output json to fetch the current DEX list before trading. The CLI does not special-case SpaceX; xyz:SPCX is only one example. Use the same selected-DEX workflow for any supported HIP-3 market.

Inspect the market before building an order:

bullpen hl price SPCX --dex xyz --output json
bullpen hl orderbook SPCX --dex xyz --output json

You can also use a DEX-prefixed market where the command accepts a coin:

bullpen hl price xyz:SPCX --output json
bullpen hl long xyz:SPCX --notional 20 --preview --output json

2. Capture Account State

Use all-DEX reads before and after any HIP-3 write:

bullpen hl status --all-dexes --output json
bullpen hl orders --all-dexes --output json

orders --all-dexes intentionally uses the richer frontend-order shape so DEX identity is preserved. In JSON, use dex_id, instrument_id, and row_key when you need to disambiguate duplicate symbols. Plain orders returns the standard Hyperliquid open-order shape. Add --dex, --all-dexes, or use frontend-orders when an agent needs DEX identity in the open-order rows.

3. Preview A Trade

Preview a long or short before signing:

bullpen hl long xyz:SPCX --notional 20 --leverage 2 --preview --output json
bullpen hl short xyz:SPCX --notional 20 --leverage 2 --preview --output json
bullpen hl long xyz:AAPL --notional 12 --preview --output json
bullpen hl short xyz:BB --notional 12 --preview --output json
bullpen hl long para:BTCD --notional 12 --preview --output json

Review these fields before live submit:

  • kind
  • coin
  • size_usd and base_size
  • effective_leverage
  • request.action
  • request.coin
  • request.tif
  • would_submit
  • signature_requested
  • exchange_request_submitted

In preview output, the submit and signature fields should be false. HIP-3 trade previews keep the DEX-qualified market in coin, for example xyz:SPCX.

Example HIP-3 preview output 
{
  "schema_version": 1,
  "kind": "hyperliquid_trade_preview",
  "action": "long",
  "coin": "xyz:SPCX",
  "side": "buy",
  "size_usd": "20",
  "base_size": "0.12",
  "effective_leverage": 5,
  "tif": "FrontendMarket",
  "estimated_avg_fill_px": "155.8",
  "estimated_taker_fee_usd": "0.0084132",
  "estimated_total_cost_usd": "0.0084132",
  "request": {
    "action": "long",
    "coin": "xyz:SPCX",
    "size_usd": "20",
    "leverage": 5,
    "tif": "FrontendMarket"
  },
  "would_submit": false,
  "signature_requested": false,
  "exchange_request_submitted": false,
  "warning": null
}

4. Submit Only After Review

Submit only after the preview matches the intended account, DEX, market, side, size, and leverage:

bullpen hl long xyz:SPCX --notional 20 --leverage 2 --yes --output json

For the explicit-DEX form:

bullpen hl long SPCX --dex xyz --notional 20 --leverage 2 --yes --output json

Both forms target the same HIP-3 market when the DEX and symbol match. Prefer the xyz:SPCX form in agent prompts because it keeps the DEX next to the market symbol.

5. Manage And Close Exposure

Inspect open orders and positions:

bullpen hl status --all-dexes --output json
bullpen hl orders --all-dexes --output json

Preview and submit a leverage change:

bullpen hl leverage xyz:SPCX 3 --preview --output json
bullpen hl leverage xyz:SPCX 3 --yes --output json

Preview and submit a close:

bullpen hl close xyz:SPCX --preview --output json
bullpen hl close xyz:SPCX --yes --output json

Preview a cancel with the DEX context if you need to cancel a resting HIP-3 order by numeric order id:

bullpen hl cancel 123456789 --dex xyz --preview --output json
bullpen hl cancel 123456789 --dex xyz --yes --output json

After any live write, rerun:

bullpen hl status --all-dexes --output json
bullpen hl orders --all-dexes --output json

Stop only when the intended HIP-3 position and orders are flat or match your target state.

Agent-Safe Workflow

Agents should use this sequence:

  1. Run bullpen hl perp-dexes --output json.
  2. Run bullpen hl markets --dex <DEX> --output json.
  3. Run bullpen hl status --all-dexes --output json.
  4. Preview the intended DEX-scoped write command with --preview --output json. Supported HIP-3 write surfaces include long, short, close, close-all, scale, stop-entry, leverage, modify, cancel, cancel-all, cancel-by-cloid, update-margin, and twap create / twap cancel.
  5. Show the user the DEX-qualified coin, side, size, effective leverage, and no-submit fields.
  6. Submit only after explicit approval by replacing --preview with --yes.
  7. Rerun all-DEX status and orders before declaring the workflow complete.
  8. For filled or historical activity, use order-status --dex, order-history --dex --symbol, or fills --dex --symbol to keep the audit scoped to rows that preserve the selected DEX identity.

Boundaries

  • Selected-DEX HIP-3 trading is supported. Use --dex <DEX> or a DEX-prefixed coin such as xyz:SPCX so the CLI signs exactly one venue-scoped mutation. DEX-scoped writes are available for long, short, close, close-all, scale, stop-entry, leverage, modify, cancel, cancel-all, cancel-by-cloid, update-margin, and TWAP create/cancel.
  • HIP-3 copy filters are not the same thing as HIP-3 manual trading. Hyperliquid copy trading has symbol-level controls; DEX-aware copy filters require a future backend contract.
  • Signed all-DEX fanout writes are not exposed. Select one DEX per mutation.
  • --all-dexes is for reads such as status and open orders.
  • Some HIP-3 DEXes can expose prices and previews while rejecting live orders for account or market-state reasons such as insufficient usable margin. In JSON mode, that case returns HYPERLIQUID_MARGIN_INSUFFICIENT. Reduce size, inspect bullpen hl balances --output json, and rerun bullpen hl status --all-dexes --output json before retrying.
  • If requested leverage exceeds the selected market maximum, JSON mode returns HYPERLIQUID_LEVERAGE_EXCEEDS_MAX with requested_leverage, max_leverage, coin, instrument_id, and perp_dex when the coin is DEX-prefixed, such as xyz:SPCX. Lower leverage to max_leverage and rerun the same command with --preview --output json.
  • order-status --dex, order-history --dex --symbol, and fills --dex --symbol are selected-DEX account-history reads. They filter only rows that preserve dex:symbol identity and avoid unsafe unscoped fallback when you supply a DEX filter.
  • orders --dex, orders --all-dexes, and frontend-orders --all-dexes remain the preferred reads for open-order state.

Generated References

Use generated references for exact flags: perp-dexes, markets, price, orderbook, long, short, close, close-all, scale, modify, leverage, update-margin, cancel, cancel-all, cancel-by-cloid, twap create, twap cancel, orders, and frontend-orders.