> ## 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.
# Perps tools
> Hyperliquid perpetuals trading with the Phantom MCP server
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
| Tool | What it returns |
| ------------------------ | ---------------------------------------------------------------------------- |
| `get_perp_markets` | Available markets, price, funding, open interest, 24h volume, max leverage |
| `get_perp_account` | Account value, available balance, available margin, withdrawable balance |
| `get_perp_positions` | Open positions, size, direction, leverage, unrealized PnL, liquidation price |
| `get_perp_orders` | Open orders including limit, TP, and SL orders |
| `get_perp_trade_history` | Historical 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:
```json theme={null}
{
"sourceChainId": "solana:mainnet",
"amount": "10",
"execute": true
}
```
Another example:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```bash theme={null}
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:
```bash theme={null}
# 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](/updates)). 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):
```json theme={null}
{
"market": "ETH",
"direction": "long",
"sizeUsd": "100",
"leverage": 5,
"orderType": "market"
}
```
Example (limit short):
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"market": "SOL",
"leverage": 3,
"marginType": "cross"
}
```
## Recommended agent flow
### 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.
## Related
Full MCP tool parameters and examples, including non-perps tools.
Install and configure the Phantom MCP server.