# @1391/hl Copy Trader

> Copy-trade any Hyperliquid trader automatically. Mirrors their positions and orders at your capital scale, with risk controls. Use when user says 'copy trade', 'follow this trader', 'mirror this HL address', 'track this wallet on Hyperliquid', or provides an HL address and capital amount.

- Skill: `starchild-ai-agent/1391-hl-copy-trader` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add starchild-ai-agent/1391-hl-copy-trader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starchild-ai-agent/1391-hl-copy-trader/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: starchild-ai-agent (https://skillmd.com/u/starchild-ai-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starchild-ai-agent/1391-hl-copy-trader

---


# HL Copy Trader

**名称 / Name:** HL Copy Trader

**描述（中文）:** 一键跟单 Hyperliquid 上的优质交易员。自动读取目标持仓，按你的资金比例等比缩放同步。资金始终在你自己的钱包中。

**Description (English):** One-click copy trading for top Hyperliquid traders. Automatically mirrors target positions scaled to your capital. Your funds stay in your own wallet.

---

## Prerequisites — Wallet Policy

Before any trade, wallet policy must be active. Load the **wallet-policy** skill and propose the standard wildcard policy (deny key export + allow `*`). Required for HL deposit, order signing, and cancellation.

---

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `target_address` | string | — | **Required.** Target trader's HL wallet address |
| `my_capital` | number | — | **Required.** Your capital in USDC |
| `risk_stop_pct` | number | 40 | Stop loss %. Liquidate all when account drops below `my_capital × (1 - risk_stop_pct/100)` |
| `sync_interval` | number | 5 | Sync frequency in minutes (1 / 3 / 5 / 15) |
| `max_leverage` | number | 10 | Cap leverage if target uses more |
| `copy_assets` | string | "all" | Coins to copy. "all" or comma-separated e.g. "BTC,ETH" |
| `min_order_size` | number | 10 | Skip scaled orders below this USDC notional |
| `risk_action` | string | "liquidate" | Action on circuit breaker trigger. `"liquidate"` = close all positions + stop (default). `"pause"` = stop sync only, notify user to decide manually — no positions touched. |

---

## Initialization Flow

Run `scripts/setup.py` to initialize. It:
1. Reads the target's current HL account value
2. Computes `scale_ratio = my_capital / target_account_value`
3. Shows a confirmation summary to the user (see below)
4. On confirm: deposits if needed, sets leverage, mirrors current positions + orders
5. Registers the sync monitor scheduled task (every `sync_interval` minutes)

**Confirmation summary to show user before starting:**
```
Target trader:   {address} (truncated)
Target capital:  ${target_value:,.0f}
Your capital:    ${my_capital:,.0f}
Scale ratio:     1 : {ratio:.0f}
Stop-loss line:  ${stop_value:,.0f} (−{risk_stop_pct}%)
Sync frequency:  every {sync_interval} min
Assets:          {copy_assets}
Max leverage:    {max_leverage}x
Confirm? (yes/no)
```

---

## Sync Loop Logic

Run `scripts/sync.py` on every scheduled trigger. Steps:

1. **Risk check first** — if `account_value < stop_value`:
   - If `risk_action == "liquidate"` (default): close all **skill-managed** positions, cancel all **skill-managed** orders, pause task, notify user.
   - If `risk_action == "pause"`: pause task immediately without touching any positions. Notify user: `"⚠️ Stop-loss triggered. Sync paused. Your positions are untouched — please decide whether to close manually."`
2. **Fetch target state** — positions + open orders via HL info API.
3. **Fetch my state** — positions + open orders + account value.
4. **Scale ratio drift check** — compare current target account value against `state.json:target_account_value_at_setup`. If drift > 20%:
   - Pause sync immediately.
   - Notify user: `"⚠️ Target account value changed from $X to $Y (>{20}%). Scale ratio would shift from 1:A to 1:B. Confirm to resume with new ratio, or reply 'keep ratio' to continue at the original scale."`
   - Wait for user confirmation before updating `scale_ratio` in state and resuming.
5. **Sync positions** — for each target position: scale size, cap leverage, open/adjust/close as needed. Only close positions that exist in `state.json:skill_positions` (skill-managed). Never touch positions not in that set.
6. **Sync orders** — cancel only orders tracked in `state.json:paul_orders` (skill-managed). Place orders target added. Skip if scaled notional < `min_order_size` or asset not in `copy_assets`. Never cancel orders not in the mapping.
7. **Notify** — only if something changed. Silent on no-op runs.

State is stored in `tasks/{job_id}/state.json`:
```json
{
  "paused": false,
  "target_address": "0x...",
  "my_capital": 1000,
  "scale_ratio": 0.01,
  "stop_value": 600,
  "sync_interval": 5,
  "max_leverage": 10,
  "copy_assets": "all",
  "min_order_size": 10,
  "paul_orders": {"target_oid": "my_oid"},
  "skill_positions": ["BTC"],
  "target_account_value_at_setup": 102000,
  "risk_action": "liquidate",
  "lang": "zh"
}
```

---

## Notifications & Reports

**Language rule:** detect language from the user's setup command. Store in `state.json` as `lang: "zh"` or `lang: "en"`. All notifications and reports follow that language. User can switch anytime by saying "report in English" or "以后用中文汇报".

**Real-time (on change only):**
- zh: `[时间] 同步完成：新增 X 笔，取消 X 笔，调整 X 笔仓位`
- en: `[time] Synced: +X orders, −X cancelled, X positions adjusted`

**Daily (UTC 00:00):**
- Account value vs starting capital
- Current positions summary (coin, side, size, unrealized PnL)
- Distance to stop-loss line
- Target trader's day performance

**Weekly (Sunday UTC 00:00):**
- Total PnL ($ and %)
- Target trader's week PnL
- Copy deviation analysis (why my % ≠ target %)
- Operation stats
- Parameter tuning suggestions

---

## Risk Warning (always show on setup)

⚠️ Copy trading carries risk. Past performance ≠ future results.
- 5-min sync delay means your fills differ from the target's
- Small scaled orders may be skipped (below `min_order_size`)
- Start with small capital to validate before scaling up
- You can stop anytime — your funds stay in your own HL account

---

## Key Implementation Notes

- Use `HyperliquidClient` from `skills/hyperliquid/client.py` for all HL calls
- **Per-coin minimum order size**: before placing any order, fetch the coin's `szDecimals` from HL `meta` API (`POST /info` with `{"type":"meta"}`). Compute `min_size = 10 ** (-szDecimals)`. Always use `max(scaled_size, min_size)`. Do not hardcode per-coin values — the `meta` response is the source of truth.
- After opening position, verify fill via `get_account_state` before confirming
- Deduplication: run cleanup pass on my orders before first sync to avoid doubling
- Scale ratio drift (>20%) always triggers a user confirmation pause — never silently update the ratio. Store `target_account_value_at_setup` in state at initialization.
- User manual orders/positions (not in `skill_positions` / `paul_orders`) are never touched by the sync loop.
- For the weekly report, compare realized PnL from fills, not mark-to-market

---

## Files

| File | Purpose |
|------|---------|
| `scripts/setup.py` | One-time initialization, confirmation, deposit, initial mirror |
| `scripts/sync.py` | Sync loop — called by scheduled task every N minutes |
| `references/api.md` | HL API notes and client method reference |