Pear Pair Trading Tutorial

Pear pair trading lets you trade a long/short Hyperliquid basket through Pear Protocol from the Bullpen CLI. Use it when you want one coordinated pair-trade workflow instead of manually opening unrelated hl long and hl short positions.

This tutorial shows the safe sequence to inspect setup, preview a pair, submit only after review, monitor the position, and clean up exposure.

Pear v1 in Bullpen supports initial take-profit and stop-loss thresholds on market pair entries, post-open TP/SL update or clear, post-open pair leverage adjustment, and pre-submit pair open --rebalance normalization. Dedicated post-open rebalance, single-position detail, and watch-style flows are still tracked for later Hyperliquid parity work because current Pear contracts do not expose stable preview/live endpoints for those surfaces.

The new post-open controls have local test-account validation. Before making them part of unattended automation, run a small live position, compare before/after pair positions output, and confirm cleanup.

Before You Start

Enable the Hyperliquid feature flags:

bullpen login
bullpen experimental enable hyperliquid
bullpen experimental enable hyperliquid_trading

hyperliquid enables reads and setup inspection. hyperliquid_trading is required for live setup, live orders, cancels, closes, risk updates, and leverage updates.

Pear uses a dedicated Hyperliquid named agent, pear-pair-trade. This is separate from ordinary Hyperliquid master-wallet signing. Before live setup, check agent slot capacity:

bullpen hl agent list --output json

If you are near Hyperliquid's agent/API wallet limit, stop and decide which automation should own each slot before approving another agent.

1. Inspect Pear Setup

Start with read-only status and setup preview:

bullpen hl pair status --output json
bullpen hl pair setup --preview --output json

These commands do not sign, create a Pear agent wallet, approve a Hyperliquid agent, approve builder fees, or submit orders. They are safe for agents to run while planning.

Look for these fields in JSON output:

• agent_can_trade
• agent_can_withdraw
• named_agent_slots_remaining
• slot_scarcity
• builder fee approval fields
• setup_complete
• session_cached
• session_fresh
• pear_agent_wallet_address
• pear_agent_wallet_available
• hyperliquid_agent_approval_submitted
• hyperliquid_builder_approval_submitted
• would_submit
• signature_requested
• pear_request_submitted

For preview output, would_submit, signature_requested, and pear_request_submitted should be false.

Example Pear setup preview output

{
  "schema_version": 1,
  "kind": "hyperliquid_pear_setup_status",
  "would_submit": false,
  "signature_requested": false,
  "pear_request_submitted": false,
  "pear_login_submitted": false,
  "pear_agent_wallet_create_submitted": false,
  "hyperliquid_agent_approval_submitted": false,
  "hyperliquid_builder_approval_submitted": false,
  "account": "0x1111111111111111111111111111111111111111",
  "pear_api_url": "https://hl-v2.pearprotocol.io",
  "pear_client_id": "APITRADER",
  "session_cached": true,
  "session_fresh": true,
  "setup_complete": true,
  "warnings": []
}

If status shows an expired or missing Pear session after setup is complete, run bullpen hl pair login --yes to sign Pear's auth challenge and cache a fresh session. This signs only the Pear login challenge; it does not open or close a position by itself.

2. Run Live Pear Setup

Only run live setup when the preview is acceptable:

bullpen hl pair setup --yes

Live setup may sign Pear auth, call Pear /agentWallet, approve the Hyperliquid named agent pear-pair-trade, and approve Pear's builder address at the configured fee cap. It should not silently re-point an existing pear-pair-trade agent slot to a different address.

If setup fails with PEAR_AUTH_CHALLENGE_FAILED, the CLI failed before any signature or Hyperliquid approval. Capture:

bullpen hl pair setup --preview --output json
bullpen hl agent list --output json

Then include the failed setup JSON in a support ticket.

3. Preview A Pair Entry

Preview a tiny long BTC / short ETH pair:

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

For a live order, Pear v1 preflight enforces:

• At least one long leg and one short leg.
• At most 15 long legs and 15 short legs.
• At least $11 * total_legs notional.
• Equal weights when no weights are provided.
• Explicit weights on every leg if any weight is provided.
• Weights that sum to 1.0 across the whole long/short portfolio within Pear's tolerance.

Weights are portfolio weights, not per-side weights. In the example below, the long side totals 0.50 and the short side totals 0.50.

Example weighted basket:

bullpen hl pair open \
  --long BTC=0.35 \
  --long ETH=0.15 \
  --short SOL=0.25 \
  --short HYPE=0.25 \
  --size-usd 44 \
  --preview \
  --output json

Use --rebalance when you want Bullpen to normalize the previewed entry into a 50% long / 50% short portfolio before submission:

bullpen hl pair open \
  --long BTC \
  --short ETH \
  --size-usd 22 \
  --rebalance \
  --preview \
  --output json

Agents should always run preview first and show the user the planned legs, notional, and no-submit fields before using --yes.

Add initial TP/SL thresholds to a market entry when you want Pear to attach pair-level risk controls at creation time:

bullpen hl pair open \
  --long BTC=0.5 \
  --short ETH=0.5 \
  --size-usd 22 \
  --take-profit 12.5 \
  --stop-loss 5 \
  --preview \
  --output json

--take-profit and --stop-loss default to percentage thresholds. Use --take-profit-type or --stop-loss-type for percentage, dollar, position-value, price, price-ratio, or weighted-ratio.

For a trailing stop loss, provide a positive trailing distance:

bullpen hl pair open \
  --long BTC=0.5 \
  --short ETH=0.5 \
  --size-usd 22 \
  --stop-loss 95000 \
  --stop-loss-type price \
  --trailing-stop \
  --trailing-delta 250 \
  --trailing-activation 96000 \
  --preview \
  --output json

Initial TP/SL thresholds are not supported with --twap-minutes; TWAP entries must be submitted without initial TP/SL.

Useful pair open controls:

Flag	Default	Notes
--leverage <N>	1	Initial Pear leverage.
--slippage <DECIMAL>	0.01	Slippage tolerance for Pear order execution.
--twap-minutes <N>		Use a TWAP entry instead of a market entry.
--twap-interval-seconds <N>		TWAP slice interval.
--randomize	false	Randomize TWAP timing when using TWAP entry.

4. Submit The Pair

After reviewing preview output and getting explicit approval, submit:

bullpen hl pair open --long BTC=0.5 --short ETH=0.5 --size-usd 22 --yes

For TWAP entry:

bullpen hl pair open --long BTC=0.5 --short ETH=0.5 --size-usd 22 --twap-minutes 30 --yes

pair open --yes requires setup to already be complete. It does not silently create a Pear agent wallet or approve builder fees while submitting an order. If Pear setup or open cannot proceed because the account lacks usable balance or completed setup, the CLI returns setup or deposit guidance before any Pear write, Hyperliquid exchange submit, approval submit, or signing.

Example Pear pair-open preview output

{
  "schema_version": 1,
  "kind": "hyperliquid_pear_open_preview",
  "would_submit": false,
  "signature_requested": false,
  "pear_request_submitted": false,
  "hyperliquid_approval_submitted": false,
  "account": "0x1111111111111111111111111111111111111111",
  "action": "open",
  "setup_complete": true,
  "request": {
    "slippage": 0.01,
    "executionType": "MARKET",
    "leverage": 1,
    "usdValue": 22.0,
    "longAssets": [{"asset": "BTC", "weight": 0.5}],
    "shortAssets": [{"asset": "ETH", "weight": 0.5}]
  }
}

Example Pear pair-open live output

{
  "kind": "hyperliquid_pear_open_result",
  "schema_version": 1,
  "source": "pear",
  "account": "0x1111111111111111111111111111111111111111",
  "success": true,
  "status": "accepted",
  "position_id": null,
  "order_id": "pear-order-1",
  "order_ids": ["pear-order-1"],
  "readback_required": true,
  "next_command": "bullpen hl pair positions --output json",
  "data": {
    "status": "accepted",
    "orderId": "pear-order-1"
  }
}

When readback_required is true, Pear accepted the request but did not return a position ID synchronously. Run the next_command, match the account and pair, and use the returned position ID for pair risk, pair leverage, or pair close.

5. Monitor Positions And Orders

Use JSON for scripts and agents:

bullpen hl pair positions --output json
bullpen hl pair orders --output json
bullpen hl pair twaps --status active --output json
bullpen hl status --all-dexes --output json
bullpen hl orders --output json

Pair reads require a Bullpen session and a cached Pear session. If read output reports a missing or expired Pear session, run bullpen hl pair login --yes, then rerun the read. Do not run live setup just to satisfy a read unless pair status or pair setup --preview shows setup is incomplete.

Pear responses use a Bullpen envelope with stable fields such as kind, schema_version, source, account, and data. The data field contains the Pear upstream payload.

Immediately after a live Pear open, pair positions can lag Pear's write acknowledgement. Poll pair positions for the Pear position ID and cross-check the underlying Hyperliquid account with hl status --all-dexes --output json before declaring setup or cleanup complete.

Without --output json, pair positions, pair orders, and pair twaps print a compact table summary of the current Pear payload. Use JSON whenever an agent or script needs the complete upstream response.

pair twaps --status active --output json is the cleanup check for running Pear TWAPs. The JSON envelope includes summary.active_count, summary.terminal_count, summary.unknown_count, and summary.needs_cleanup. pair twaps --status all can include historical terminal rows, including cancelled TWAPs, so do not treat a non-empty all-status list as active risk by itself. Use the TWAP summary plus pair positions, pair orders, and the underlying hl status --all-dexes --output json flatness check before declaring a Pear workflow cleaned up.

6. Update Risk Or Leverage

These post-open controls are live mutation paths. They have preview coverage, local regression tests, and test-account validation. Run the same before/after pair positions checks on a small position before putting them into automation.

Preview post-open TP/SL changes before submitting them:

bullpen hl pair risk <POSITION_ID> --take-profit 12 --stop-loss 5 --preview --output json
bullpen hl pair risk <POSITION_ID> --clear-take-profit --preview --output json
bullpen hl pair risk <POSITION_ID> --clear-stop-loss --preview --output json

Submit only after the preview is acceptable:

bullpen hl pair risk <POSITION_ID> --take-profit 12 --stop-loss 5 --yes
bullpen hl pair risk <POSITION_ID> --clear-take-profit --yes
bullpen hl pair risk <POSITION_ID> --clear-stop-loss --yes

pair risk updates Pear risk parameters when live. It requires completed Pear setup plus a fresh Pear session, and never creates a Pear agent wallet or approves Hyperliquid agents as a side effect. If Pear returns a retryable error after a live submit starts, check pair positions and pair orders before retrying because the update state may be unknown. Setup and deposit blockers return guidance before signing or submitting. Pear service-side auth rejection after a live write is no-replay; inspect pair positions and orders before retrying.

Preview and submit leverage changes separately:

bullpen hl pair leverage <POSITION_ID> --leverage 4 --preview --output json
bullpen hl pair leverage <POSITION_ID> --leverage 4 --yes

pair leverage updates Pear leverage when live. Like other Pear mutations, live submit requires completed Pear setup and --yes; after retryable submit errors, inspect pair state before retrying.

7. Close Or Cancel

Preview one close:

bullpen hl pair close <POSITION_ID> --preview

Use --twap-minutes, --twap-interval-seconds, and --randomize on pair close when you want to close one Pear position over time instead of with a market close.

Submit one close:

bullpen hl pair close <POSITION_ID> --yes

Close all Pear positions:

bullpen hl pair close-all --preview --output json

Cancel a market order or TWAP:

bullpen hl pair cancel <ORDER_ID> --preview --output json
bullpen hl pair cancel-twap <ORDER_ID> --preview --output json

After reviewing the preview, rerun the exact cleanup command with --yes only when the target position, order, or TWAP id is correct.

pair close-all is market-only in v1. Use pair close <POSITION_ID> --twap-minutes <N> for a TWAP close of one Pear position.

Agent-Safe Workflow

Agents should use this sequence:

1. Run bullpen hl pair status --output json.
2. Run bullpen hl pair setup --preview --output json.
3. If setup is incomplete, explain what live setup would do and ask the user before running bullpen hl pair setup --yes.
4. Preview the intended pair order with --preview --output json.
5. Show the legs, weights, notional, and no-submit fields to the user.
6. Submit only after explicit user approval by replacing --preview with --yes.
7. Preview any post-open risk or leverage change before submitting it.
8. Read pair positions, pair orders, pair twaps --status active, hl status, and hl orders after submission.
9. Close or cancel until Pear and Hyperliquid account reads show no unintended exposure.

Never infer that ordinary hl long, hl short, or hl close is equivalent to Pear. Pear has its own session, agent wallet, builder approval, order IDs, and cleanup commands.

Generated References

Use generated references for exact flags: hl pair, status, setup, login, open, positions, orders, twaps, risk, leverage, close, close-all, cancel, and cancel-twap.