hyperliquid-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hyperliquid-mcp What are my open orders?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hyperliquid MCP Server
An MCP server implementation that integrates the Hyperliquid SDK.
π Prerequisites
Node.js (v22.0.0 or higher)
pnpm or yarn package manager
Basic understanding of cryptocurrency trading concepts
Related MCP server: Hyperliquid MCP Server
π Installation
Option 1: Install from pnpm (Recommended)
# Install globally
pnpm install -g hyperliquid-mcp
# Or install locally in your project
pnpm install hyperliquid-mcpOption 2: Install from Source
Clone this repository:
git clone cd hyperliquid-mcpInstall dependencies:
pnpm installBuild the project:
pnpm run build
ποΈ Configuration
Create a .env file with your credentials:
# This is your wallet private key
PRIVATE_KEY=your_private_keyπ Usage with Claude Desktop
To add this MCP server to Claude Desktop:
Create or edit the Claude Desktop configuration file at:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add the following configuration:
{
"mcpServers": {
"hyperliquid-mcp": {
"command": "node",
"args": ["/path/to/hyperliquid-mcp/dist/index.js"],
"env": {
"PRIVATE_KEY": "your_private_key_here"
},
"disabled": false,
"autoApprove": []
}
}
}Restart Claude Desktop for the changes to take effect.
π NPX
{
"mcpServers": {
"hyperliquid-mcp": {
"command": "npx",
"args": ["-y", "hyperliquid-mcp"]
},
"env": {
"PRIVATE_KEY": "your_private_key_here"
}
}
}π§© Supported Tools
get_spot_clearinghouse_state
Get the clearinghouse state of a user on Hyperliquid.
{
user?: string; // User address (optional, defaults to wallet address)
}Example query to Claude:
"Show me my spot account state."
get_perp_clearinghouse_state
Get the perpetual clearinghouse state of a user on Hyperliquid.
{
user?: string; // User address (optional, defaults to wallet address)
}Example query to Claude:
"Show me my perps account state."
get_order_status
Get the status of a specific order.
{
user: string; // User address
oid: number | string; // Order ID
}Example query to Claude:
"check my wallet order: o123456 status"
get_open_orders
Get all open orders for a user.
{
user?: string; // User address (optional, defaults to wallet address)
}Example query to Claude:
"check all my open orders"
get_order_history
Get order history for a user.
{
user?: string; // User address (optional, defaults to wallet address)
}Example query to Claude:
"check my account order history"
get_all_mids
Get mid prices for all coins on Hyperliquid.
get_spot_meta
Request spot trading metadata.
get_candle_snapshot
Get historical candlestick data.
{
coin: string; // Token symbol, e.g. "BTC"
interval: string; // Time interval, e.g. "15m", "1h", "4h", "1d"
startTime: number; // Start timestamp in milliseconds
endTime?: number; // End timestamp in milliseconds (optional)
}get_l2_book
Get L2 order book data.
{
coin: string; // Token symbol, e.g. "BTC-PERP", "ETH-PERP", "SOL-PERP", "BTC-SPOT"
}place_order
Place a trading order.
{
coin: string; // Token symbol
is_buy: boolean; // true for buy, false for sell
sz: number; // Order size
limit_px: number; // Limit price
tif?: "Gtc" | "Ioc" | "Alo"; // Time-in-force (optional)
reduce_only?: boolean; // Reduce-only flag (optional)
vaultAddress?: string; // Vault address (optional)
is_limit?: boolean; // Limit order flag (optional)
trigger_px?: number; // Trigger price (optional)
is_market?: boolean; // Market order flag (optional)
tpsl?: "tp" | "sl"; // Take-profit/Stop-loss type (optional)
}Example query to Claude:
"Create a HYPE limit order for $10 and set the target price to $20"
cancel_order
Cancel an existing order.
{
coin: string; // Token symbol
o: number; // Order ID
}Example query to Claude:
"Cancel the order we created earlier"
transfer_spot_perp
Transfer between spot and perpetual accounts.
{
amount: number; // Transfer amount
to_perp: boolean; // true for transfer to perpetual, false for transfer to spot
}Example query to Claude:
"Transfer $10 from spot to perps"
Response Format
Each tool returns a Promise that resolves with:
Success: Returns corresponding data object
Failure: Throws an error with error message
Note: All numerical parameters accept both number and string inputs. The system will automatically handle type conversion as needed.
π Security Considerations
Private Key Protection: Never expose or hardcode your private key. Use environment variables.
Consider using environment variables or a secure credential manager instead of hardcoding sensitive information.
Be cautious when transferring funds or deploying contracts, as these operations are irreversible on the blockchain.
When using the onramp functionality, ensure you're on a secure connection.
Verify all transaction details before confirming, especially when transferring funds or buying credits.
π· Troubleshooting
If you encounter issues:
Verify that your wallet private key is valid
Check the Claude Desktop logs for any error messages
π License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
π€ Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
For detailed guidelines on contributing to Hyperliquid MCP, including:
Reporting bugs
Suggesting enhancements
Development setup
Coding standards
Adding tools
Testing requirements
Documentation standards
Basic contribution steps:
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
Please make sure your code follows the existing style and includes appropriate tests.
Built with β€οΈ by Impa Ventures
Available Tools
12 toolscancel_orderC
Cancel an order on Hyperliquid
Inputs: o (required), coin (required).
get_all_midsA
Get mid prices for all coins on Hyperliquid
Inputs: no named parameters.
get_candle_snapshotB
Get candlestick data for a token on Hyperliquid
Inputs: coin (required), interval (required), startTime (required), endTime.
get_l2_bookB
Get the L2 book of a token on Hyperliquid
Inputs: coin, required.
get_open_ordersA
Get all open orders on Hyperliquid, if no user is provided, the open orders of the wallet address will be returned
Inputs: user.
get_order_historyA
Get all order history on Hyperliquid, if no user is provided, the order history of the wallet address will be returned
Inputs: user.
get_order_statusB
Get the status of an order on Hyperliquid
Inputs: oid (required), user (required).
get_perp_clearinghouse_stateB
Get the clearinghouse state of a user on Hyperliquid, if no user is provided, the clearinghouse state of the wallet address will be returned
Inputs: user.
get_spot_clearinghouse_stateB
Get the clearinghouse state of a user on Hyperliquid, if no user is provided, the clearinghouse state of the wallet address will be returned
Inputs: user.
get_spot_metaC
Request spot trading metadata
Inputs: no named parameters.
orderC
Place an order on Hyperliquid
Inputs: sz (required), coin (required), is_buy (required), limit_px (required), +7 more.
transfer_spot_perpA
Transfer spot to perp, or perp to spot, based on the toPerp value
Inputs: amount (required), to_perp.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 12 tools
The tools are mostly distinct, with clear separation between spot and perp clearinghouse states, and different order-related queries (status, open, history). There is slight potential confusion between 'order' and 'get_order_status', but descriptions clarify the intended purpose.
Most read-only tools follow the 'get_' prefix convention, but 'order', 'cancel_order', and 'transfer_spot_perp' do not, mixing bare verbs with the prefix pattern. The names are readable but not fully consistent in style.
With 12 tools, the server is well-scoped for its purpose, covering account state, order lifecycle, market data, and transfers without being overwhelming. Each tool serves a clear function within the trading domain.
The tool set covers core trading workflows, including querying state, managing orders, and fetching market data. Minor gaps exist, such as no explicit trade history, modify order capability, or position-specific endpoints, but these are workable for most use cases.
Maintenance
Related MCP Connectors
Hyperliquid market data, wallet analytics and liquidation alerts for AI agents.
Build, backtest and paper-run Hyperliquid strategies from your AI assistant.
Trade Hyperliquid perpetual futures from your Ask Gina wallet. Moves real funds.
AI research desk for Hyperliquid: ranked opportunities and trade theses. You confirm every trade.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceEnables interaction with the Hyperliquid DEX for retrieving market data, managing positions, and executing trades. Supports both testnet and mainnet operations with comprehensive trading tools including order placement, cancellation, and portfolio management.11MIT
- AlicenseAqualityDmaintenanceEnables interaction with the Hyperliquid exchange to trade perpetuals, check positions, and manage risk through natural language. It provides tools for fetching real-time market data, tracking portfolio value, and executing orders with a focus on safety through default paper trading.101MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely trade on Hyperliquid perpetual exchange, including order placement, position management, market data retrieval, and vault operations via natural language.29 PyPI24MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to interact directly with the Hyperliquid decentralized exchange, allowing natural language trading, market analysis, and strategy automation.1MIT