gdex-perp-copy-trading
HyperLiquid perpetual futures copy trading — discover top perp traders, create/manage perp copy trades, fill history, opposite-direction copying, and market data
SKILL.mdskills/gdex-perp-copy-trading/SKILL.md
GitHubGDEX: Perp Copy Trading (HyperLiquid)
Automatically mirror perpetual futures positions (long/short) from top-performing HyperLiquid traders. Supports opposite-direction copying, fixed or proportional sizing, and TP/SL controls.
This is completely separate from Solana spot copy trading (
gdex-copy-trading). Different chain (EVM, chainId=1 vs Solana 622112261), different ABI methods (hl_create/hl_updatevscreate_copy_trade/update_copy_trade), different field schemas. On both chainsisDeletedeletes the configuration andisChangeStatustogglesisActive(pause/resume); neither closes positions.
When to Use
- Browsing top HyperLiquid perp traders (by volume, PnL, or deposit)
- Getting detailed trading stats for a specific trader
- Creating a perp copy trade to follow a trader's long/short positions
- Updating or deleting a perp copy trade
- Viewing perp copy trade fill history with enrichment
- Checking market data (assets, DEXes, clearinghouse state, open orders)
- Checking deposit tokens and USDC balance
Prerequisites
@gemachdao/gdex-skillinstalled- For discovery:
loginWithApiKey()only - For read (list/tx_list): Full sign-in with session key (
chainId: 1) - For write (create/update): Full sign-in + computedData
Auth Tiers
| Tier | Endpoints | Auth Needed |
|---|---|---|
| Discovery | top_traders, top_traders_by_pnl, user_stats, perp_dexes, all_assets, clearinghouse_state, open_orders, deposit_tokens, usdc_balance |
API key only |
| Read | list, tx_list |
Session-key auth (userId + encrypted data) |
| Write | create, update |
computedData (ABI-encode + sign + AES-encrypt) |
Key Differences from Solana Copy Trading
| Feature | Solana (gdex-copy-trading) |
HL Perp (gdex-perp-copy-trading) |
|---|---|---|
| Chain | Solana (622112261) | EVM (chainId = 1) |
| Asset Type | Spot tokens | Perpetual futures (long/short) |
| ABI Methods | create_copy_trade / update_copy_trade |
hl_create / hl_update |
| ABI Fields | 12 create / 15 update (typed: uint64, bool, uint64[]) | 8 create / 11 update (typed: copyMode uint64, bool flags) |
| Opposite Copy | ❌ Not supported | ✅ oppositeCopy flag |
isChangeStatus |
Toggles isActive (use pauseCopyTrade/resumeCopyTrade) |
Toggles isActive (use pauseHlCopyTrade/resumeHlCopyTrade) |
| Copy Modes | 1=fixed SOL, 2=% of trader | 1=fixed USD per order, 2=proportion of trader's size |
| TP/SL | Optional | Mandatory (both > 0, lossPercent < 100) |
| Max Copies | config.maxCopyTrades |
Default 3 (hyperLiquidConfig.maxFuturesCopy) |
Discovery Endpoints (No Auth)
Top Traders by Volume/TradeCount/Deposit
const topByVolume = await skill.getHlTopTraders('volume');
const topByTrades = await skill.getHlTopTraders('tradeCount');
const topByDeposit = await skill.getHlTopTraders('deposit');
// Cached 15 minutes
Top 30 Traders by PnL
const topPnl = await skill.getHlTopTradersByPnl();
// Response: { isSuccess: true, topTraders: { day: [...], week: [...], month: [...] } }
// Each entry: { ethAddress, accountValue, windowPerformances: [{ window, percentage, pnl }] }
Detailed User Stats
// NOTE: Requires the MANAGED wallet address, not the control wallet.
// Control wallet and external trader addresses return "Wallet not found".
const stats = await skill.getHlUserStats('0xManagedWalletAddress');
// Cached 1 hour in Redis
HlUserStats Shape
interface HlUserStats {
'24h': number; // PnL last 24 hours
'7d': number; // PnL last 7 days
'30d': number; // PnL last 30 days
week: number;
dailyPnls: Array<{
timeMs: number;
date: string;
pnl: number;
pnlPercentage: number;
capitalDeployed: number;
}>;
volumes: Record<string, number>;
tradesCount: Record<string, { win: number; lose: number; total: number }>;
percentagePnl: Record<string, number>;
capitalDeployed: Record<string, number>;
allTime: { pnl: number; pnlPercentage: number; capitalDeployed: number };
}
Perp DEXes
const dexes = await skill.getHlPerpDexes();
// { isSuccess: true, perpDexes: ['HyperLiquid', ...] }
All Tradeable Assets
const assets = await skill.getHlAllAssets();
// { isSuccess: true, count: N, assets: [...] }
Clearinghouse State (Account Positions)
// Single DEX
const state = await skill.getHlClearinghouseState('0xTraderAddress');
// All DEXes
const stateAll = await skill.getHlClearinghouseStateAll('0xTraderAddress');
Open Orders
// Single DEX
const orders = await skill.getHlOpenOrdersForCopy('0xTraderAddress');
// All DEXes
const ordersAll = await skill.getHlOpenOrdersAllForCopy('0xTraderAddress');
Deposit Tokens
const tokens = await skill.getHlDepositTokens();
// { isSuccess: true, tokens: { "42161": [{ name, symbol, address, chainId, decimals, minDeposit, HLReceiver }] } }
// Key is chain ID ("42161" = Arbitrum One)
USDC Balance (Arbitrum)
const balance = await skill.getHlUsdcBalanceForCopy('0xTraderAddress');
Read Endpoints (Session-Key Auth)
Require userId and data (AES-encrypted session key from buildGdexUserSessionData).
List User's HL Copy Trades
import { buildGdexUserSessionData } from '@gemachdao/gdex-skill';
const data = buildGdexUserSessionData(sessionKey, apiKey);
const list = await skill.getHlCopyTradeList({ userId, data });
// { isSuccess: true, count: 2, allCopyTrades: [...] }
HlCopyTradeConfig Shape
interface HlCopyTradeConfig {
copyTradeId: string;
copyTradeName: string;
copyMode: number; // 1 or 2; configs written by SDK <= 4.12 hold 416/480 (string-encoded ABI)
chainId: number; // Always 1 (EVM)
isActive: boolean;
userId: string;
userWallet: string; // MANAGED wallet address
traderWallet: string; // EVM address
lossPercent: number;
profitPercent: number;
fixedAmountCostPerOrder: string;
oppositeCopy: boolean; // configs written by SDK <= 4.12 hold true regardless of the request
createdAt: number;
lastUpdated: number;
totalTrades: number;
totalVolumes: number;
totalPnl: number;
}
Fill History
const txList = await skill.getHlCopyTradeTxList({
userId,
data,
page: '1',
limit: '20', // max 100
});
// { isSuccess: true, totalCount: 42, txes: [...] }
// Cached 15 seconds
HlCopyTradeTx Shape
interface HlCopyTradeTx {
coin: string; // e.g. "BTC"
px: string; // Fill price
sz: string; // Fill size
side: string; // "B" (buy) or "S" (sell)
time: number; // Unix ms
closedPnl: string;
oid: string; // HyperLiquid order ID
dir: string; // e.g. "Open Long"
copyTradeName: string; // or "N/A"
traderTxHash: string; // or "N/A"
traderSize: string; // or "N/A"
traderPrice: string; // or "N/A"
traderWallet: string; // or "N/A"
}
Write Endpoints (ComputedData Auth)
Create an HL Perp Copy Trade
await skill.createHlCopyTrade({
apiKey,
userId,
sessionPrivateKey,
traderWallet: '0xTraderEvmAddress',
copyTradeName: 'BTC Whale Follower',
copyMode: 1, // Fixed USD amount per order
fixedAmountCostPerOrder: '50000000', // $50 per copied trade (raw USDC, 6 decimals)
lossPercent: '25', // 25% stop-loss (mandatory, > 0)
profitPercent: '100', // 100% take-profit (mandatory, > 0)
oppositeCopy: false, // Copy same direction
});
ABI Schema (hl_create, 8 fields, typed as backend decoder.ts decodes it):
| # | Field | Type | Description |
|---|---|---|---|
| 0 | traderWallet | string | EVM address to copy |
| 1 | copyTradeName | string | Human-readable label |
| 2 | copyMode | uint64 | 1 or 2 |
| 3 | fixedAmountCostPerOrder | string | Mode 1: raw USDC, 6 decimals ('50000000' = $50); mode 2: percentage |
| 4 | lossPercent | string | Stop-loss % |
| 5 | profitPercent | string | Take-profit % |
| 6 | nonce | string | Auto-generated |
| 7 | oppositeCopy | bool |
Update, Pause, Resume, Delete
Use the explicit operations. Each reads the current configuration first (the backend rewrites every field on update), so pass only what changes.
const ids = { apiKey, userId, sessionPrivateKey, copyTradeId: 'abc123...' };
// Settings only; never deletes or pauses. Omitted fields keep current values.
await skill.updateHlCopyTradeSettings({ ...ids, copyMode: 2, fixedAmountCostPerOrder: '0.5', oppositeCopy: false });
await skill.pauseHlCopyTrade(ids); // isActive=false, no-op if already paused
await skill.resumeHlCopyTrade(ids); // isActive=true, no-op if already active
await skill.deleteHlCopyTrade(ids); // permanent
| Operation | Backend effect (ServiceHyperLiquid.update) |
Open perp positions / TP-SL |
|---|---|---|
updateHlCopyTradeSettings |
rewrites the config fields | unchanged |
pauseHlCopyTrade |
toggle → isActive=false; the copier skips inactive configs for opens AND closes |
stay open and will not follow the trader's exits; TP/SL stays |
resumeHlCopyTrade |
toggle → isActive=true |
fills made while paused are not replayed |
deleteHlCopyTrade |
HLFuturesCopySetting.deleteOne |
NOT closed, TP/SL NOT cancelled |
Pause/resume raise PAUSE_STATE_UNVERIFIED when the current state cannot be
read (nothing is sent) and PAUSE_UNSUPPORTED when the stored copyMode is not
1 or 2 (a config written by SDK <= 4.12): repair it with
updateHlCopyTradeSettings({ copyMode, fixedAmountCostPerOrder, oppositeCopy })
first, or delete (positions stay open). The low-level updateHlCopyTrade still
exists; setting both isDelete and isChangeStatus is rejected.
ABI Schema (hl_update, 11 fields, typed):
| # | Field | Type | Description |
|---|---|---|---|
| 0 | traderWallet | string | EVM address |
| 1 | copyTradeName | string | Label |
| 2 | copyMode | uint64 | 1 or 2 |
| 3 | fixedAmountCostPerOrder | string | Amount or ratio |
| 4 | lossPercent | string | Stop-loss % |
| 5 | profitPercent | string | Take-profit % |
| 6 | nonce | string | Auto-generated |
| 7 | isDelete | bool | |
| 8 | isChangeStatus | bool | toggles isActive |
| 9 | copyTradeId | string | Existing trade ID |
| 10 | oppositeCopy | bool |
Backend Quirks (Live E2E Findings)
These are verified behaviors observed during live E2E testing.
Legacy
copyModevalues. SDK versions up to 4.12 encoded everyhl_create/hl_updatefield as an ABI string. The backend decodescopyModeasuint64and the flags asbool, so it stored the head-slot offset (416 after create, 480 after update) ascopyModeandtrueforoppositeCopy, and readisDelete=trueon every update (which is why updates "always deleted"). The SDK now sends the typed ABI. Configs created by old versions keep the bad values until you callupdateHlCopyTradeSettingswith explicit ones.isChangeStatustogglesisActive(isActive = !existing.isActive); it does not delete. OnlyisDeletedeletes. Neither closes positions.The copier only mirrors
isActive: trueconfigs (copyTradeHyperLiquid.ts), for both opens and closes.user_statsrequires the MANAGED wallet address (userWalletfrom the copy trade config), not the control wallet address. The control wallet and external trader wallets return{"code":103,"error":"Wallet not found"}.Discovery endpoints use different query params:
user_stats:?user=<address>(managed wallet only)clearinghouse_state,clearinghouse_state_all:?address=<address>open_orders,open_orders_all:?address=<address>usdc_balance:?address=<address>
top_traders_by_pnlreturns nested structure:{ day: [...], week: [...], month: [...] }where each entry hasethAddress,accountValue, andwindowPerformances.deposit_tokensresponse keys are chain IDs (e.g.,"42161"for Arbitrum), not chain names. Each token includesname,symbol,address,chainId,decimals,minDeposit,HLReceiver.
Backend Validation Rules
- TP/SL mandatory: Both
lossPercent> 0 (and < 100) andprofitPercent> 0 - Copy modes: Mode 1 = fixed USD per order, Mode 2 = proportion of trader's size
- Max copies: Default 3 per user (
hyperLiquidConfig.maxFuturesCopy) - No self-copy: Can't copy your own wallet
- Circular dependency: Full DFS graph cycle detection (A→B→C→A prevented)
- No duplicates: Can't copy the same trader wallet twice
How Copies Execute
Copies are NOT executed at API call time. A background watcher monitors tracked traders:
- Detects trader's new perp position (open/close/modify)
- Calculates your position size based on copyMode
- Opens/closes a mirrored position (or opposite if
oppositeCopy=true) - Applies TP/SL based on your lossPercent/profitPercent settings
- Tracks fill in
HLCopyTradeTrackcollection for tx_list
Example: Full HL Perp Copy Trading Flow
import {
GdexSkill,
buildGdexUserSessionData,
generateGdexSessionKeyPair,
buildGdexSignInMessage,
buildGdexSignInComputedData,
} from '@gemachdao/gdex-skill';
import { ethers } from 'ethers';
const skill = new GdexSkill();
skill.loginWithApiKey(apiKey);
// 1. Sign in (chainId: 1 for HL operations)
const wallet = ethers.Wallet.fromPhrase(mnemonic);
const { sessionPrivateKey, sessionKey } = generateGdexSessionKeyPair();
const nonce = String(Date.now());
const msg = buildGdexSignInMessage(wallet.address, nonce, sessionKey);
const sig = await wallet.signMessage(msg);
const payload = buildGdexSignInComputedData({
apiKey, userId: wallet.address, sessionKey, nonce, signature: sig,
});
await skill.signInWithComputedData({ computedData: payload.computedData, chainId: 1 });
const data = buildGdexUserSessionData(sessionKey, apiKey);
const userId = wallet.address.toLowerCase();
// 2. Discover top traders
const topTraders = await skill.getHlTopTradersByPnl();
const bestTrader = topTraders.topTraders[0];
console.log(`Top trader: ${bestTrader.address}, volume: $${bestTrader.volume}`);
// 3. Check trader's stats
const stats = await skill.getHlUserStats(bestTrader.address);
console.log(`30d PnL: $${stats.userStats['30d']}`);
// 4. Create a copy trade
await skill.createHlCopyTrade({
apiKey,
userId,
sessionPrivateKey,
traderWallet: bestTrader.address,
copyTradeName: `Top PnL: ${bestTrader.address.slice(0, 8)}`,
copyMode: 1,
fixedAmountCostPerOrder: '25000000', // $25 per copied trade (raw USDC, 6 decimals)
lossPercent: '30',
profitPercent: '100',
});
// 5. Monitor
const list = await skill.getHlCopyTradeList({ userId, data });
for (const ct of list.allCopyTrades) {
console.log(`${ct.copyTradeName}: active=${ct.isActive}, trades=${ct.totalTrades}, PnL=$${ct.totalPnl}`);
}
// 6. Check fill history
const fills = await skill.getHlCopyTradeTxList({ userId, data, limit: '20' });
for (const tx of fills.txes) {
console.log(`${tx.coin} ${tx.dir}: ${tx.sz} @ $${tx.px}, PnL=${tx.closedPnl}`);
}
Autonomous Agent Notes (Live-Tested)
getHlUserStats()requires the MANAGED wallet address. Passing the control address or any external trader address returns 400"Wallet not found". Use the managed EVM address from/v1/user?chainId=1.- All 7 other discovery endpoints (topTraders, topTradersByPnl, allAssets, perpDexes, depositTokens, clearinghouseState, openOrders) work with the control address or any external address. Only
user_statshas the managed-address requirement. - A
copyModeother than 1 or 2 in a response is a legacy config written by SDK <= 4.12; repair it withupdateHlCopyTradeSettings. - To pause, call
pauseHlCopyTrade, never delete. Pausing leaves copied positions open and unmanaged by the copier. - Sign-in for HL copy trading must use
chainId: 1(EVM), not622112261(Solana).
Related Skills
- gdex-authentication — Auth setup and sign-in required for read/write
- gdex-copy-trading — Solana spot copy trading (separate system)
- gdex-perp-trading — HL perp order management, positions, leverage
- gdex-perp-funding — Deposit/withdraw USDC to HL account
- gdex-portfolio — Monitor portfolio including copied positions