Perps Copy Trading Tutorial¶

Perps copy trading lets you follow a Hyperliquid leader account through the experimental hl copy surface. It depends on Bullpen account-service feature enablement and is separate from Prediction copy trading under tracker copy; do not mix the two workflows.

Use this tutorial to inspect copy-trading state, preview a subscription, set risk limits, manage manual confirmations, pause/resume, and stop safely.

Before You Start¶

Enable Hyperliquid reads:

bullpen login
bullpen experimental enable hyperliquid

Enable live copy-trading mutations only when you intend to create, update, pause, resume, stop, confirm, reject, or change risk:

bullpen experimental enable hyperliquid_trading

1. Inspect Current State¶

Start with read-only state:

bullpen hl copy list --include-stopped --output json
bullpen hl copy show <SUBSCRIPTION_ID> --output json
bullpen hl copy stats --output json
bullpen hl copy pending --output json
bullpen hl copy executions --limit 25 --output json
bullpen hl copy open-positions --output json
bullpen hl copy risk config --output json

These commands do not create subscriptions, approve executions, change risk limits, or submit exchange orders.

If you have a leader address or Bullpen username, inspect it first:

bullpen hl copy leader-profile <LEADER> --output json

2. Preview A Subscription¶

Preview a fixed-notional subscription:

bullpen hl copy start <LEADER> \
  --fixed-notional 25 \
  --max-notional-per-order 50 \
  --daily-notional-limit 250 \
  --confirm-each \
  --copy-only-new-positions \
  --preview \
  --output json

Review:

leader address or Bullpen username
resolved Bullpen user metadata when available
nickname
sizing mode and notional or percentage
per-order and daily limits
confirmation mode
exit behavior
allowed coin filters
would_mutate
would_mutate_if_submitted
would_sign_or_submit
core_ready
backend_contract_status
unsupported_flags
missing_backend_contracts
request

Preview does not create or reactivate a subscription. Exactly one sizing flag is required: --fixed-notional, --copy-percent, --balance-percent, or --mirror-percent-cap.

include_spot, allowed_dexes, and blocked_dexes can appear in preview payloads, but they are not live availability claims. Bullpen can record those preferences, but the current copy listener does not execute spot, staked-asset, or DEX-filtered copy flows yet. Live start/update rejects those options until they are supported end to end.

Example copy-subscription preview output

{
  "action": "start",
  "backend_contract_status": "not_applicable",
  "core_ready": true,
  "error_code": null,
  "kind": "hyperliquid_copy_preview",
  "message": null,
  "missing_backend_contracts": [],
  "request": {
    "behavior": {
      "confirm_each": true,
      "confirm_timeout_seconds": null,
      "copy_only_new_positions": true,
      "copy_reduce_only": false,
      "exit_behavior": "mirror_sells",
      "include_spot": false,
      "mirror_stop_loss": false,
      "mirror_take_profit": false
    },
    "filters": {
      "allowed_coins": [],
      "allowed_dexes": [],
      "blocked_coins": [],
      "blocked_dexes": []
    },
    "leader": "0x1111111111111111111111111111111111111111",
    "nickname": null,
    "risk": {
      "consecutive_loss_pause_threshold": null,
      "daily_loss_limit_percent": null,
      "daily_notional_limit": 250.0,
      "leverage_cap": null,
      "max_notional_per_order": 50.0,
      "max_open_positions": null,
      "max_position_notional": null,
      "max_slippage_bps": null,
      "perp_position_type": null,
      "stop_loss_percent": null
    },
    "sizing": {
      "allocated_capital_usd": null,
      "balance_percent": null,
      "copy_percent": null,
      "fixed_notional": 25.0,
      "min_trade_size_usd": null,
      "mirror_percent_cap": null,
      "total_budget_usd": null
    }
  },
  "status": "ready",
  "unsupported_flags": [],
  "would_mutate": false,
  "would_mutate_if_submitted": true,
  "would_sign_or_submit": false
}

Example unsupported spot-copy preview output

{
  "kind": "hyperliquid_copy_preview",
  "action": "start",
  "would_mutate": false,
  "would_mutate_if_submitted": false,
  "would_sign_or_submit": false,
  "core_ready": false,
  "status": "unsupported",
  "error_code": "hyperliquid_copy_unsupported_flags",
  "backend_contract_status": "missing",
  "message": "Bullpen can record the include-spot preference, but the current copy listener does not execute spot or staked-asset copy yet.",
  "unsupported_flags": ["--include-spot"],
  "missing_backend_contracts": [
    "CopyTradeService.v2_spot_listener_include_spot_execution"
  ],
  "request": {
    "leader": "0x1111111111111111111111111111111111111111",
    "behavior": {
      "include_spot": true
    }
  }
}

3. Create Or Update After Review¶

Create the subscription only after reviewing the preview:

bullpen hl copy start <LEADER> \
  --fixed-notional 25 \
  --max-notional-per-order 50 \
  --daily-notional-limit 250 \
  --confirm-each \
  --copy-only-new-positions \
  --yes \
  --output json

hl copy start accepts either a 0x... leader address or a Bullpen username without the @ prefix. It can create a new subscription or reactivate/update a stopped subscription for the same leader identity. Store the returned subscription id from JSON output and use it for later commands.

Proportional sizing uses the same preview-first flow:

bullpen hl copy start <LEADER> \
  --copy-percent 25 \
  --max-notional-per-order 50 \
  --preview \
  --output json

Update a subscription with the id:

bullpen hl copy update <SUBSCRIPTION_ID> --fixed-notional 20 --preview --output json
bullpen hl copy update <SUBSCRIPTION_ID> --fixed-notional 20 --yes --output json

4. Configure Account-Level Risk¶

Preview risk changes:

bullpen hl copy risk config set \
  --max-notional-per-order 50 \
  --daily-notional-limit 250 \
  --max-open-positions 3 \
  --preview \
  --output json

Submit only after review:

bullpen hl copy risk config set \
  --max-notional-per-order 50 \
  --daily-notional-limit 250 \
  --max-open-positions 3 \
  --yes \
  --output json

Reset risk config only when you intend to return to defaults:

bullpen hl copy risk config reset --preview --output json

After reviewing the reset preview, rerun the command with --yes only if you intend to return to the service defaults.

5. Review Pending Executions¶

If the subscription uses confirmation mode, review pending executions:

bullpen hl copy pending --output json

Confirm or reject one execution:

bullpen hl copy confirm <EXECUTION_ID> --yes --output json
bullpen hl copy reject <EXECUTION_ID> --yes --output json

confirm and reject mutate copy-trading execution state. Read the pending payload before running either command.

6. Pause, Resume, Or Stop¶

Pause without deleting the subscription:

bullpen hl copy pause <SUBSCRIPTION_ID> --preview --output json
bullpen hl copy pause <SUBSCRIPTION_ID> --yes --output json

Resume:

bullpen hl copy resume <SUBSCRIPTION_ID> --preview --output json
bullpen hl copy resume <SUBSCRIPTION_ID> --yes --output json

Stop:

bullpen hl copy stop <SUBSCRIPTION_ID> --preview --output json
bullpen hl copy stop <SUBSCRIPTION_ID> --yes --output json

Live stop JSON includes status: "stopped", id, subscription_id, target, stopped_at, updated_at, observed_at, and readback_status. Hyperliquid copy stop does not currently return a dedicated stop timestamp, so stopped_at is null unless Bullpen returns one later. The CLI tries to read the stopped subscription after the mutation and fills updated_at from that readback. If readback is unavailable or has no update timestamp, updated_at stays null and observed_at records when the CLI saw the stop command succeed.

After stopping, check state:

bullpen hl copy cleanup-status --output json
bullpen hl copy list --include-stopped --output json
bullpen hl copy open-positions --subscription <SUBSCRIPTION_ID> --output json
bullpen hl status --all-dexes --output json

Use cleanup-status as the first cleanup proof. It combines subscription state, pending confirmations, open copy positions, and risk counters into has_live_copy_state plus a next_action. Use list --include-stopped when you need audit history; stopped subscriptions are not active copy state by themselves.

Inspect one subscription:

bullpen hl copy show <SUBSCRIPTION_ID> --output json

Read aggregate copy-trading stats:

bullpen hl copy stats --output json

Agent-Safe Workflow¶

Agents should use this sequence:

Run hl copy list --include-stopped --output json.
Run hl copy risk config --output json.
Preview hl copy start or hl copy update with --preview --output json.
Show the leader, sizing, limits, confirmation mode, and no-submit fields to the user.
Submit only after explicit approval with --yes.
Use subscription ids from JSON output, not leader addresses, for update, pause, resume, stop, and open-position filters.
Check cleanup-status, pending, executions, open-positions, and hl status --all-dexes after any live change.

Boundaries¶

Hyperliquid copy trading is experimental and depends on Bullpen service availability.
tracker copy is Polymarket-only.
Leader identity can be a Hyperliquid wallet address or a Bullpen username when Bullpen can resolve that username to a selected Arbitrum wallet.
Reads require an authenticated Bullpen session and the hyperliquid experimental feature. Run bullpen doctor auth --output json if reads fail before changing subscription state.
The current public CLI does not expose coin filters, DEX filters, reduce-only copy mode, mirrored stop-loss, or mirrored take-profit because Bullpen does not yet enforce those settings safely for copied trades. --max-open-positions is account-level risk config; set it with hl copy risk config set --max-open-positions <N>.
copy start --include-spot is a presence-only switch. Omit it for perps-only copy trading. copy update --include-spot false is accepted as an explicit perps-only update setting. Setting --include-spot true is not a live availability claim: preview output reports that copied spot execution is not yet supported, and live create/update rejects it until service support is proven.
DEX-aware HIP-3 copy filters are not available for copied trades yet. Manual HIP-3 trading is documented separately in HIP-3 Perps Trading.

Generated References¶

Use generated references for exact flags: hl copy, start, update, list, show, stats, executions, pending, confirm, reject, open-positions, leader-profile, pause, resume, stop, cleanup-status, risk config, risk config set, and risk config reset.