{"success":true,"data":{"service":"HyperX Copy-Trading API","base_url":"https://api-service.hyperx.trade","authentication":{"trading_api_token":{"header":"x-hyperx-trading-token","description":"Trading API Token for AI Agent access. Create via POST /api/user/trading-token (requires user session auth). Token never expires; revoke manually.","how_to_obtain":["User logs into HyperX app","Navigate to Settings → Trading API Token","Create a new token with a descriptive name","Copy the token value (shown only once on creation)","Use this token in x-hyperx-trading-token header for all API calls"],"management_endpoints":{"create":"POST /api/user/trading-token — body: { name: string }","list":"GET /api/user/trading-token — returns list with token_preview","revoke_one":"DELETE /api/user/trading-token/{id}","revoke_all":"DELETE /api/user/trading-token"},"limits":{"max_tokens_per_user":5,"expiry":"never (revoke manually)"},"permissions":["Wallet listing & status check","Copy-trading configuration (create, update, list, delete, toggle)","Copy-trading order management (cancel, close position)","Manual trading (place order, close, TP/SL, leverage)","Deposit check"]}},"response_envelope":{"description":"All responses are wrapped: { success: true, data: <payload> }. Errors return { success: false, message: \"...\" }.","example_success":{"success":true,"data":"<payload>"},"example_error":{"success":false,"message":"error description"}},"url_pattern":{"description":"Most endpoints use global prefix /api/{exchange}/. The {exchange} path param is always 'Hyperliquid'.","example":"https://api-service.hyperx.trade/api/Hyperliquid/copy-trading/list"},"concepts":{"follow_types":{"fundingRatio":"Copy based on the master wallet's funding/margin ratio relative to account balance. Follower order size scales proportionally to their own account balance.","fixedAmount":"Every copied trade uses a fixed margin amount (set via fixed_margin_amount). Simple and predictable.","positionRatio":"Copy based on position size ratio. Uses ratio_scaling as multiplier. E.g. master opens 10% of account with ratio_scaling=2 → follower opens 20%."},"margin_modes":{"follow":"Use the same margin mode as the master wallet.","cross":"Always use cross margin for all copied positions.","isolate":"Always use isolated margin for all copied positions."},"wallet_types":{"HYPER_LIQUID_API":"Mainnet Hyperliquid API wallet. For real trading (is_testnet=false).","HYPER_LIQUID_API_DEV":"Testnet Hyperliquid API wallet. For paper trading (is_testnet=true).","EVM":"Standard EVM wallet. Cannot be used for copy-trading."},"leverage":{"description":"fixed_leverage and max_leverage are mutually exclusive. Set one to null when using the other.","fixed_leverage":"Use this exact leverage for all copied trades.","max_leverage":"Cap leverage at this value; actual leverage follows the master up to this limit."},"copy_controls":{"follow_increase":"When true, copies the master's position increase.","follow_decrease":"When true, copies the master's position decrease (partial close).","follow_margin_change":"When true, syncs margin adjustments with the master.","copy_increase_as_open_position":"When true, treats master's position increase as a new independent open rather than adding to existing.","reverse_copy":"When true, trades opposite direction (master long → follower short).","copy_current_position":"When true on creation, immediately copies the master's existing open positions."},"coin_filtering":{"copy_trading_allow_list":"If set (non-null array), ONLY these coins will be copied.","copy_trading_block_list":"If set (non-null array), these coins will NEVER be copied."}},"workflow":{"description":"Step-by-step guide for an AI agent to set up copy-trading.","steps":[{"step":1,"action":"List wallets","method":"GET","path":"/api/Hyperliquid/wallet/list","note":"Get available wallets. Only HYPER_LIQUID_API (mainnet) or HYPER_LIQUID_API_DEV (testnet) wallets with active=true can be used for copy-trading."},{"step":2,"action":"Identify master wallet to follow","note":"Determine the Hyperliquid wallet address to copy-trade. This is any external wallet address you want to follow."},{"step":3,"action":"Create copy-trading config","method":"POST","path":"/api/Hyperliquid/copy-trading/create","note":"Create a copy-trading configuration linking your wallet to the master wallet."},{"step":4,"action":"Monitor & manage","note":"Use /copy-trading/list to check status, /copy-trading/active to enable/disable. Use /trading/position/close to close copy-traded positions manually."}]},"constraints":["is_testnet=true requires HYPER_LIQUID_API_DEV wallet; is_testnet=false requires HYPER_LIQUID_API wallet.","fixed_leverage and max_leverage are mutually exclusive — one must be null when the other has a value.","Cannot follow your own wallet (wallet_address ≠ copy_wallet_address).","Max configs: 5 for regular users, 20 for premium users.","DELETE is soft-delete — stops future copying but preserves existing open positions.","Cannot change copy_wallet_address or wallet_address after creation (use delete + create instead).","Wallet must be active (active=true) and not expired to be used for copy-trading."],"wallet_discovery":{"description":"To find high-performing wallets worth following, use the HyperX Data API.","data_api_base_url":"https://data-api.hyperx.trade","recommended_endpoints":[{"path":"/api/wallet/analysis","description":"Get comprehensive wallet performance analysis (PnL, win rate, Sharpe ratio, etc.)","params":"wallet_address (required)"},{"path":"/api/wallet/metrics","description":"Get wallet performance metrics summary","params":"wallet_address (required)"}],"note":"Data API endpoints do not require authentication. Use wallet analysis data to evaluate potential master wallets before setting up copy-trading."},"positions_and_balances":{"description":"Query account positions, balances, and margin information via Hyperliquid clearinghouse endpoints.","base_url":"https://api-service.hyperx.trade","endpoints":[{"method":"POST","path":"/api/hyperliquid/clearinghouseState","description":"Get a wallet's positions, margin, account value, and unrealized PnL. Returns merged data from all DEXs by default.","auth":"required (x-hyperx-trading-token or x-faster100x-api-token)","request_body":{"user":"string — wallet address to query","is_testnet":"boolean — optional, default false","dex":"string|null — optional, 'xyz' | 'flx' | 'vntl'. If null, merges all DEXs."},"response_schema":{"marginSummary":{"accountValue":"string — total account value in USD","totalMarginUsed":"string — margin in use","totalNtlPos":"string — total notional position","totalRawUsd":"string — USD balance"},"assetPositions":[{"position":{"coin":"string — e.g. BTC","szi":"string — signed size (negative = short)","leverage":{"type":"string","value":"string"},"entryPx":"string — entry price","positionValue":"string","unrealizedPnl":"string","returnOnEquity":"string","liquidationPx":"string|null","marginUsed":"string"}}]}},{"method":"POST","path":"/api/hyperliquid/allDexsClearinghouseState","description":"Get positions across all DEXs in a single call. Returns per-DEX breakdown.","auth":"required","request_body":{"user":"string — wallet address","is_testnet":"boolean — optional"}}]},"error_codes":{"description":"Error codes returned in copy-trading operations. These appear in order execution logs and API error responses.","codes":{"-1":"UNKNOWN_ERROR — Unexpected error during copy-trading execution","-1001":"BALANCE_INSUFFICIENT — Follower wallet does not have enough balance","-1002":"TRADE_AMOUNT_ERROR — Calculated trade amount is invalid","-1003":"TRADE_COPY_AMOUNT_ERROR — Master trade amount could not be determined","-1004":"TRADE_AMOUNT_TOO_SMALL — Calculated order size is below minimum","-1005":"META_AND_ASSETS_CTXS_NOT_FOUND — Could not fetch coin metadata/asset info","-2001":"API_MY_CLEARING_HOUSE_STATE_FAILED — Failed to fetch follower wallet state from Hyperliquid","-2002":"API_COPY_CLEARING_HOUSE_STATE_FAILED — Failed to fetch master wallet state from Hyperliquid","-2003":"API_COPY_POSITION_NOT_FOUND — Master position not found (may have already closed)","-2004":"API_COPY_WALLET_BALANCE_ERROR — Master wallet balance query error","-2005":"API_MY_POSITION_NOT_FOUND — Follower position not found for close/decrease operation","-2006":"API_PLACE_ORDER_FAILED — Order placement failed on Hyperliquid","-20061":"API_PLACE_ORDER_TOO_MANY_CUMULATIVE_REQUEST_FAILED — Rate limited by Hyperliquid","-20062":"API_PLACE_ORDER_CAN_NOT_PLACE_ORDER_MORE_AGGRESSIVE_FAILED — Order price too aggressive","-20063":"API_PLACE_ORDER_HIP_3_ABSTRACT_FAILED — HIP-3 abstract order error","-20064":"API_PLACE_ORDER_API_WALLET_NOT_EXISTS — API wallet not found on Hyperliquid","-20065":"API_PLACE_ORDER_BUILD_FEE_NOT_APPROVED — Builder fee not approved for this wallet","-20066":"API_PLACE_ORDER_TOO_MANY_OPEN_ORDERS — Too many open orders on this wallet","-2007":"API_META_AND_ASSETS_CTXS_FAILED — Hyperliquid meta/asset context API call failed"},"handling_advice":{"balance_errors":"For -1001 (insufficient balance), check account balance via /api/hyperliquid/clearinghouseState and consider depositing funds.","rate_limits":"For -20061 (rate limited), wait 1-2 seconds and retry.","wallet_errors":"For -20064 (wallet not exists) or -20065 (fee not approved), check wallet active status via /wallet/check/active."}},"categories":[{"name":"Wallet Management","description":"Manage trading wallets. Required to obtain wallet_address for copy-trading setup.","endpoints":[{"method":"GET","path":"/api/Hyperliquid/wallet/list","description":"List all wallets for the authenticated user. Returns wallet addresses, types, and active status.","auth":"required","response_schema":{"wallets":[{"alien":"string — wallet display name","address":"string — wallet address (use for copy-trading wallet_address)","master_address":"string|null — master address for API wallets","type":"EVM | HYPER_LIQUID_API | HYPER_LIQUID_API_DEV","isPrimary":"boolean","active":"boolean — must be true for copy-trading","wallet_type":"EVM | HYPER_LIQUID_API | HYPER_LIQUID_API_DEV","created_at":"number — timestamp ms","updated_at":"number — timestamp ms","expired_at":"number|null — API wallet expiry timestamp ms"}]}},{"method":"POST","path":"/api/Hyperliquid/wallet/check/active","description":"Check if a wallet is activated and ready for trading.","auth":"required","request_body":{"address":"string — wallet address to check"},"response_schema":{"active":"boolean","can_update":"boolean","builder":"string — builder fee wallet address","max_fee_rate":"number — commission fee rate"}}]},{"name":"Copy-Trading Configuration","description":"Create, update, list, delete, and toggle copy-trading configurations.","endpoints":[{"method":"POST","path":"/api/Hyperliquid/copy-trading/create","description":"Create a new copy-trading config. Links your wallet to a master wallet.","auth":"required","request_body":{"is_active":"boolean — enable immediately","is_testnet":"boolean — true=testnet, must match wallet type","wallet_address":"string — YOUR wallet address from /wallet/list (HYPER_LIQUID_API or HYPER_LIQUID_API_DEV only)","name":"string — display name for this config","copy_wallet_address":"string — master wallet address to follow","followType":"fundingRatio | fixedAmount | positionRatio","marginMode":"follow | cross | isolate","follow_increase":"boolean","follow_decrease":"boolean","follow_margin_change":"boolean — optional, default false","copy_increase_as_open_position":"boolean|null — optional","ratio_scaling":"number|null — required if followType=positionRatio (e.g. 1.0 = 1:1)","fixed_margin_amount":"number|null — required if followType=fixedAmount (USD per trade)","max_margin_amount":"number|null — max margin per trade in USD, null=no limit","min_margin_amount":"number — min margin per trade, must > 0, default 1","max_leverage":"number|null — max leverage cap (mutually exclusive with fixed_leverage)","fixed_leverage":"number|null — exact leverage (mutually exclusive with max_leverage)","margin_amount_limit_with_leverage":"boolean — optional, apply leverage to margin limits","tp_percent":"number|null — take profit %, e.g. 50 = +50%, null=no TP","sl_percent":"number|null — stop loss %, e.g. 20 = -20%, null=no SL","copy_current_position":"boolean|null — copy master's existing positions on creation","reverse_copy":"boolean|null — trade opposite direction","copy_trading_allow_list":"string[]|null — whitelist coins e.g. ['BTC','ETH'], null=all","copy_trading_block_list":"string[]|null — blacklist coins, null=none blocked"},"response_schema":{"copyTrading":{"id":"string — UUID, use for update/delete/toggle","...":"all request fields echoed back with id added"},"wallet":{"address":"string","type":"string","active":"boolean"}},"example_request":{"is_active":true,"is_testnet":false,"wallet_address":"0xYourApiWalletAddress","name":"Follow Top Trader","copy_wallet_address":"0xMasterWalletAddress","followType":"fixedAmount","marginMode":"cross","follow_increase":true,"follow_decrease":true,"fixed_margin_amount":100,"max_margin_amount":500,"min_margin_amount":10,"max_leverage":10,"fixed_leverage":null,"tp_percent":null,"sl_percent":null,"copy_current_position":false,"reverse_copy":false,"copy_trading_allow_list":null,"copy_trading_block_list":null}},{"method":"PUT","path":"/api/Hyperliquid/copy-trading/update/{id}","description":"Update an existing copy-trading config. Cannot change copy_wallet_address or wallet_address.","auth":"required","request_body":{"is_active":"boolean","is_testnet":"boolean","name":"string","marginMode":"follow | cross | isolate","follow_increase":"boolean","follow_decrease":"boolean","follow_margin_change":"boolean — optional","copy_increase_as_open_position":"boolean|null — optional","ratio_scaling":"number — optional","max_margin_amount":"number — optional","min_margin_amount":"number","max_leverage":"number|null","fixed_leverage":"number|null","fixed_margin_amount":"number — optional","margin_amount_limit_with_leverage":"boolean — optional","tp_percent":"number — optional","sl_percent":"number — optional","reverse_copy":"boolean|null","copy_trading_allow_list":"string[]|null","copy_trading_block_list":"string[]|null"}},{"method":"GET","path":"/api/Hyperliquid/copy-trading/list","description":"List all copy-trading configs for the authenticated user.","auth":"required","response_schema":{"copyTradingList":["CopyTradingDto — same shape as create response .copyTrading"],"walletList":["WalletDto — wallet details for each config"]}},{"method":"DELETE","path":"/api/Hyperliquid/copy-trading/{id}","description":"Soft-delete a copy-trading config. Stops copying but preserves existing open positions.","auth":"required"},{"method":"PUT","path":"/api/Hyperliquid/copy-trading/active","description":"Enable or disable a copy-trading config without deleting it.","auth":"required","request_body":{"id":"string — copy-trading config UUID","is_active":"boolean — true=enable, false=pause"}}]},{"name":"Wallet Fund Operations","description":"Deposit, withdraw, and transfer funds between wallets. Needed to ensure wallets have sufficient balance before copy-trading.","endpoints":[{"method":"POST","path":"/api/Hyperliquid/wallet/deposit","description":"Trigger a deposit check for a wallet. Detects pending L1→Hyperliquid deposits.","auth":"required","request_body":{"wallet_address":"string — your wallet address"}},{"method":"POST","path":"/api/Hyperliquid/wallet/exchange/withdraw","description":"Withdraw USDC from a Hyperliquid wallet to another address.","auth":"required","note":"Requires password or passkey verification.","request_body":{"wallet_address":"string — source wallet address","destination_address":"string — destination address","amount":"number — USDC amount to withdraw","password":"string — wallet password (required if no passkey)","passkey":"PasskeyVerification|null — optional, alternative to password"}},{"method":"POST","path":"/api/Hyperliquid/wallet/exchange/transfer/usd","description":"Transfer USDC between your own wallets within Hyperliquid (internal transfer, no L1 tx).","auth":"required","note":"Requires password or passkey verification.","request_body":{"wallet_address":"string — source wallet address","destination_address":"string — destination wallet address","amount":"number — USDC amount","is_testnet":"boolean — optional, true if testnet transfer","password":"string — wallet password (required if no passkey)","passkey":"PasskeyVerification|null — optional, alternative to password"}}]},{"name":"Manual Trading (Perp)","description":"Place perpetual orders, close positions, set TP/SL, and manage leverage directly. Also used for manual intervention on copy-traded positions.","note":"All symbol fields use CCXT standard format, e.g. \"BTC/USD:USDC\" (base/quote:settle).","endpoints":[{"method":"POST","path":"/api/Hyperliquid/trading/order/place","description":"Place a new perpetual order (market, limit, or post-only).","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional, default false","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","side":"'buy' | 'sell'","order_type":"'market' | 'limit' | 'post_only'","price":"string — order price","size":"string — order size in coin units","is_cross":"boolean — true=cross margin, false=isolated","reduce_only":"boolean — true=reduce-only order","sl_price":"string|null — optional stop-loss trigger price","tp_price":"string|null — optional take-profit trigger price"}},{"method":"POST","path":"/api/Hyperliquid/trading/order/cancel","description":"Cancel a pending/resting order.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","order_id":"string (numeric) — order ID to cancel"}},{"method":"POST","path":"/api/Hyperliquid/trading/position/close","description":"Close a position (fully or partially).","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","ratio":"number — 0 to 1 (1 = full close)"}},{"method":"POST","path":"/api/Hyperliquid/trading/position/reverse","description":"Reverse a position (close current + open opposite direction).","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","side":"'buy' | 'sell' — new direction (opposite of current position)","is_cross":"boolean","price":"string — current market price","size":"string — position size"}},{"method":"POST","path":"/api/Hyperliquid/trading/position/trigger/tp_sl","description":"Set take-profit / stop-loss on an existing position.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","side":"'buy' | 'sell' — position side","is_cross":"boolean","size":"string — position size","tp_price":"string|null — take-profit trigger price","sl_price":"string|null — stop-loss trigger price"}},{"method":"POST","path":"/api/Hyperliquid/trading/position/leverage/update","description":"Update leverage for a specific symbol.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","leverage":"string — new leverage value","is_cross":"boolean — true=cross, false=isolated"}},{"method":"POST","path":"/api/Hyperliquid/trading/position/margin/update","description":"Add or remove isolated margin on a position.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"BTC/USD:USDC\"","side":"'buy' | 'sell' — position side","margin":"string — margin delta (positive=add, negative=remove)"}}]},{"name":"Spot Trading","description":"Place spot orders, swap tokens, and perform stablecoin exchanges.","note":"All symbol fields use CCXT standard format, e.g. \"HYPE/USDC\" (base/quote).","endpoints":[{"method":"POST","path":"/api/Hyperliquid/trading/spot/place","description":"Place a new spot order (market, limit, or post-only).","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional, default false","symbol":"string — CCXT format, e.g. \"HYPE/USDC\"","side":"'buy' | 'sell'","order_type":"'market' | 'limit' | 'post_only'","size":"string — order size in base token units","price":"string|undefined — required for limit/post_only orders"}},{"method":"POST","path":"/api/Hyperliquid/trading/spot/cancel","description":"Cancel a pending spot order.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","symbol":"string — CCXT format, e.g. \"HYPE/USDC\"","order_id":"string (numeric) — order ID to cancel"}},{"method":"POST","path":"/api/Hyperliquid/trading/spot/swap","description":"Swap tokens (market order). Automatically resolves symbol and side from token pair.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","from_token":"string — source token, e.g. \"USDC\"","to_token":"string — destination token, e.g. \"HYPE\"","amount":"string — amount of from_token to swap","slippage":"number|undefined — optional slippage tolerance (0-1)"}},{"method":"POST","path":"/api/Hyperliquid/trading/spot/stablecoin-swap","description":"Swap between stablecoins. Both tokens must be stablecoins.","auth":"required","request_body":{"wallet_address":"string — your wallet address","is_testnet":"boolean — optional","from_token":"string — source stablecoin, e.g. \"USDC\"","to_token":"string — destination stablecoin, e.g. \"USDT\"","amount":"string — amount to swap"}}]}]}}