Overview
Hyperliquid perps in the MCP server use two balances on Hypercore:- Spot account: receives bridged funds and holds transferable tokens
- Perp account: holds USDC collateral for perpetual positions
- external chain -> Hyperliquid spot (
perps_deposit) - Hyperliquid spot -> perp account (
perps_transfer) - open / manage positions
- perp account -> external chain (
perps_withdraw)
perps_withdraw-hl-spot MCP tool or the phantom perps withdraw-hl-spot CLI command.
All perps write operations use the wallet’s EVM signing path on
eip155:42161 for Hyperliquid actions. The funding tools are different: they use the Phantom bridge / swap flows where appropriate.What agents can do with perps
These tools let an agent do more than just place a single trade. An agent can:- inspect available perp markets and compare price, funding, open interest, and leverage limits
- check account value, available balance, and the amount available to trade
- open long or short positions with configurable leverage
- choose between market and limit orders
- watch open positions and active orders over time
- change leverage or margin mode after a trade is open
- close part or all of a position when the user asks
- move funds into and out of the perp account as part of a larger workflow
- “Open a 5x BTC long with $250 of exposure.”
- “Place a limit ETH short if price comes back to 3,200.”
- “Show me my open SOL perp and close half of it.”
- “Move my remaining USDC out of perps and withdraw it back to Base.”
Read-only tools
Funding and withdrawal tools
perps_deposit
Bridges or swaps from an external chain into Hyperliquid. This is the entry point when funds are not already on Hypercore.
Typical use:
- user has SOL / ETH / USDC on an external chain
- call
perps_deposit - funds arrive in Hyperliquid spot as USDC
- call
perps_transferto move that USDC into the perp account
perps_transfer
Moves USDC within Hypercore from spot into the perp account. This is an internal Hyperliquid transfer, not a bridge.
Parameters:
amountUsdc: amount of USDC to move from spot to perpsderivationIndex(optional): account derivation index, defaults to0
perps_withdraw
Bridges USDC from the Hyperliquid perpetuals account to an external chain.
Parameters:
amountUsdc: amount of USDC to bridge outdestinationChainId: destination chain such assolana:mainnet,eip155:8453,eip155:42161buyToken(optional): CAIP-19 token to receive; defaults to USDC on the destination chainderivationIndex(optional): account derivation index, defaults to0
Withdrawing from Hyperliquid spot
If funds are in your Hyperliquid spot account rather than the perps account, call theperps_withdraw-hl-spot MCP tool or the phantom perps withdraw-hl-spot CLI command to bridge them to an external chain. This is useful when you have USDC sitting in spot after a deposit or after moving funds out of perps.
--amountUsdc: amount of USDC to bridge out--destinationChainId: destination chain such assolana:mainnet,eip155:8453,eip155:1,eip155:42161,eip155:137--buyToken(optional): CAIP-19 token to receive on the destination chain; defaults to USDC--execute(optional): set totrueto sign and broadcast immediately; defaults to returning a quote only
--execute to preview the quote before committing:
execute. Use perps_withdraw to withdraw from the perps account directly.
Trading tools
perps_open
Opens a long or short position. Supports:
- market orders
- limit orders
- leverage selection
- isolated or cross margin
- reduce-only flag
market: market symbol such asBTC,ETH,SOLdirection:longorshortsizeUsd: notional position size in USD, as a numberleverage: leverage multiplierorderType(required):marketorlimitlimitPrice(required for limit orders): target price as a numbermarginType(optional):isolated(default) orcrossreduceOnly(optional): if true, order can only reduce an existing positionderivationIndex(optional): account derivation index, defaults to0
perps_close
Closes a position fully or partially using sizePercent.
Parameters:
market: market symbol to closesizePercent(optional): percentage of the position to close, defaults to100derivationIndex(optional): account derivation index, defaults to0
perps_cancel
Cancels an open order by orderId.
Parameters:
market: market symbolorderId: numeric order id fromperps_ordersderivationIndex(optional): account derivation index, defaults to0
perps_leverage
Changes leverage and margin mode for a market.
Parameters:
market: market symbolleverage: leverage multipliermarginType(required):crossorisolatedderivationIndex(optional): account derivation index, defaults to0
Recommended agent flow
Funding a perp account
wallet_balancesperps_depositperps_transferperps_account
Opening and managing a trade
perps_marketsperps_accountperps_openperps_positionsperps_ordersperps_leverageorperps_cancelas needed
Exiting and withdrawing
perps_closeperps_withdraw(bridges USDC from perps directly to destination chain)
perps_withdraw-hl-spot MCP tool or the phantom perps withdraw-hl-spot CLI command.
Notes for agents
- If the user asks for their total Hyperliquid exposure, do not rely only on
wallet_balances; also callperps_account. - If the user asks to move funds off Hyperliquid, check
perps_accountto see where the USDC is. Callperps_withdrawwith adestinationChainIdfor funds in the perp account. Callperps_withdraw-hl-spotwith adestinationChainIdfor funds in Hyperliquid spot. Each handles the bridge in one step. - If the user already has funds in Hyperliquid spot, skip
perps_depositand useperps_transferdirectly.
Related
Tool reference
Full MCP tool parameters and examples, including non-perps tools.
MCP setup
Install and configure the Phantom MCP server.