Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.phantom.com/llms.txt

Use this file to discover all available pages before exploring further.

The Phantom MCP server includes a dedicated set of tools for perpetuals trading on Hyperliquid through Phantom’s backend. This page focuses only on those perps tools: what they do, how funding flows work, and the order agents should use them in.

​
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
The usual funding path is:
  1. external chain -> Hyperliquid spot (deposit_to_hyperliquid)
  2. Hyperliquid spot -> perp account (transfer_spot_to_perps)
  3. open / manage positions
  4. perp account -> external chain (withdraw_from_perps)
To withdraw funds from the Hyperliquid spot account (instead of perps), use 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 margin, and withdrawable balance
  • 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
Typical user requests this enables:
  • “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.”
Perps tools can open leveraged positions and submit irreversible actions. Agents should confirm high-impact trades and withdrawals with the user before executing them.

​
Read-only tools

ToolWhat it returns
get_perp_marketsAvailable markets, price, funding, open interest, 24h volume, max leverage
get_perp_accountAccount value, available balance, available margin, withdrawable balance
get_perp_positionsOpen positions, size, direction, leverage, unrealized PnL, liquidation price
get_perp_ordersOpen orders including limit, TP, and SL orders
get_perp_trade_historyHistorical fills, fees, and closed PnL

​
Funding and withdrawal tools

​
deposit_to_hyperliquid

Bridges or swaps from an external chain into Hyperliquid. This is the entry point when funds are not already on Hypercore. Typical use:
  1. user has SOL / ETH / USDC on an external chain
  2. call deposit_to_hyperliquid
  3. funds arrive in Hyperliquid spot as USDC
  4. call transfer_spot_to_perps to move that USDC into the perp account
Example: 
{
  "sourceChainId": "solana:mainnet",
  "amount": "10",
  "execute": true
}
Another example: 
{
  "sourceChainId": "eip155:42161",
  "amount": "250",
  "sellTokenMint": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "execute": true
}

​
transfer_spot_to_perps

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 perps
  • derivationIndex (optional): account derivation index, defaults to 0
Example: 
{
  "amountUsdc": "100"
}

​
withdraw_from_perps

Bridges USDC from the Hyperliquid perpetuals account to an external chain. Parameters:
  • amountUsdc: amount of USDC to bridge out
  • destinationChainId: destination chain such as solana:mainnet, eip155:8453, eip155:42161
  • buyToken (optional): CAIP-19 token to receive; defaults to USDC on the destination chain
  • derivationIndex (optional): account derivation index, defaults to 0
Example: 
{
  "amountUsdc": "50",
  "destinationChainId": "solana:mainnet"
}

​
Withdrawing from Hyperliquid spot (CLI only)

If funds are in your Hyperliquid spot account rather than the perps account, use 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. 
phantom perps withdraw-hl-spot --amountUsdc 50 --destinationChainId solana:mainnet
Parameters:
  • --amountUsdc: amount of USDC to bridge out
  • --destinationChainId: destination chain such as solana: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 to true to sign and broadcast immediately; defaults to returning a quote only
Omit --execute to preview the quote before committing: 
# Preview the quote
phantom perps withdraw-hl-spot --amountUsdc 50 --destinationChainId eip155:8453

# Execute after reviewing
phantom perps withdraw-hl-spot --amountUsdc 50 --destinationChainId eip155:8453 --execute
Moved from the MCP server to the CLI. Earlier releases exposed this as the withdraw_from_hyperliquid_spot MCP tool (see prior changelog entries). It has since been removed from the MCP server and is now available only via phantom perps withdraw-hl-spot in the CLI. The withdraw_from_perps MCP tool is still the right choice for withdrawing from the perps account directly.

​
Trading tools

​
open_perp_position

Opens a long or short position. Supports:
  • market orders
  • limit orders
  • leverage selection
  • isolated or cross margin
  • reduce-only flag
Parameters:
  • market: market symbol such as BTC, ETH, SOL
  • direction: long or short
  • sizeUsd: notional position size in USD
  • leverage: leverage multiplier
  • orderType: market or limit
  • limitPrice (required for limit orders): target price as a string
  • marginType (optional): isolated or cross
  • reduceOnly (optional): if true, order can only reduce an existing position
  • derivationIndex (optional): account derivation index, defaults to 0
Example (market long): 
{
  "market": "ETH",
  "direction": "long",
  "sizeUsd": "100",
  "leverage": 5,
  "orderType": "market"
}
Example (limit short): 
{
  "market": "BTC",
  "direction": "short",
  "sizeUsd": "500",
  "leverage": 10,
  "orderType": "limit",
  "limitPrice": "72000",
  "marginType": "isolated"
}

​
close_perp_position

Closes a position fully or partially using sizePercent. Parameters:
  • market: market symbol to close
  • sizePercent (optional): percentage of the position to close, defaults to 100
  • derivationIndex (optional): account derivation index, defaults to 0
Example: 
{
  "market": "ETH",
  "sizePercent": 50
}

​
cancel_perp_order

Cancels an open order by orderId. Parameters:
  • market: market symbol
  • orderId: numeric order id from get_perp_orders
  • derivationIndex (optional): account derivation index, defaults to 0
Example: 
{
  "market": "BTC",
  "orderId": 12345
}

​
update_perp_leverage

Changes leverage and margin mode for a market. Parameters:
  • market: market symbol
  • leverage: leverage multiplier
  • marginType: cross or isolated
  • derivationIndex (optional): account derivation index, defaults to 0
Example: 
{
  "market": "SOL",
  "leverage": 3,
  "marginType": "cross"
}

​
Funding a perp account

  1. get_token_balances
  2. deposit_to_hyperliquid
  3. transfer_spot_to_perps
  4. get_perp_account

​
Opening and managing a trade

  1. get_perp_markets
  2. get_perp_account
  3. open_perp_position
  4. get_perp_positions
  5. get_perp_orders
  6. update_perp_leverage or cancel_perp_order as needed

​
Exiting and withdrawing

  1. close_perp_position
  2. withdraw_from_perps (bridges USDC from perps directly to destination chain)
To withdraw USDC from Hyperliquid spot via the CLI, use phantom perps withdraw-hl-spot.

​
Notes for agents

  • If the user asks for their total Hyperliquid exposure, do not rely only on get_token_balances; also call get_perp_account.
  • If the user asks to move funds off Hyperliquid, call withdraw_from_perps with a destinationChainId — it handles the full bridge in one step.
  • If the user already has funds in Hyperliquid spot, skip deposit_to_hyperliquid and use transfer_spot_to_perps directly.

Tool reference

Full MCP tool parameters and examples, including non-perps tools.

MCP setup

Install and configure the Phantom MCP server.