| Name | hyperliquid-mcp JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | None |
| Summary | A server that exposes a set of tools for interacting with the Hyperliquid decentralized exchange. It simplifies trading operations by providing a high-level API for placing, canceling, and modifying orders, as well as managing account settings and retrieving market data. |
| upload_time | 2025-07-29 02:24:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2025 Hyperliquid MCP Server
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
crypto
defi
exchange
hyperliquid
mcp
trading
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Hyperliquid MCP Server
A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with the Hyperliquid decentralized exchange. This server enables AI assistants to perform trading operations, manage accounts, and retrieve market data through a standardized interface.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
## 🚀 Features
- **29 Trading Tools** - Complete coverage of Hyperliquid's API
- **Account Management** - Positions, balances, transfers, and leverage control
- **Order Management** - Place, cancel, modify orders with advanced features
- **Market Data** - Real-time prices, orderbooks, candles, and funding rates
- **Risk Management** - Order simulation and validation
- **Type Safety** - Full Pydantic validation for all inputs
- **Error Handling** - Comprehensive error reporting and logging
## 📦 Installation
### Using uvx (Recommended)
```bash
uvx hyperliquid-mcp
```
### Using uv
```bash
uv add hyperliquid-mcp
uv run hyperliquid-mcp
```
### Using pip
```bash
pip install hyperliquid-mcp
hyperliquid-mcp
```
## ⚙️ Configuration
### Environment Variables
Configure the following environment variables:
```bash
# Required for trading operations
export HYPERLIQUID_PRIVATE_KEY="your_private_key_here"
# Optional: Specify a different user address for queries (defaults to wallet address)
export HYPERLIQUID_USER_ADDRESS="0x1234567890123456789012345678901234567890"
# Optional: Use testnet instead of mainnet (default: false)
export HYPERLIQUID_TESTNET="true"
```
> ⚠️ **Security Warning**: Never share your private key. The server will warn if the key is missing but will still start in read-only mode for market data.
#### Environment Variable Details
- **`HYPERLIQUID_PRIVATE_KEY`** (Required for trading): Your wallet's private key for signing transactions
- **`HYPERLIQUID_USER_ADDRESS`** (Optional): Ethereum address to query data for. If not set, uses the address derived from your private key
- **`HYPERLIQUID_TESTNET`** (Optional): Set to `"true"` to use Hyperliquid's testnet for development and testing
### 👤 User Address Configuration
The server supports querying data for different users:
- **Default behavior**: Uses the address derived from your `HYPERLIQUID_PRIVATE_KEY`
- **Custom user**: Set `HYPERLIQUID_USER_ADDRESS` to query a different address
- **Tool-level override**: Many tools accept a `user` parameter to query specific addresses
**Use cases:**
- Monitor multiple accounts from one server instance
- Query public data for other traders (positions, fills, etc.)
- Portfolio management for multiple wallets
- Analytics and research on other users' trading activity
### 🧪 Testnet Configuration
For development and testing, you can use Hyperliquid's testnet:
1. **Enable testnet mode** by setting `HYPERLIQUID_TESTNET=true`
2. **Get testnet tokens** from the [Hyperliquid testnet faucet](https://app.hyperliquid-testnet.xyz/faucet)
3. **Use testnet-specific addresses** - testnet has separate contracts and addresses
4. **Test safely** - All trades execute on testnet without real financial risk
> 💡 **Tip**: Always test your trading strategies on testnet before using real funds on mainnet.
### Claude Desktop Configuration
Add to your Claude Desktop `claude_desktop_config.json`:
```json
{
"mcpServers": {
"hyperliquid": {
"command": "uvx",
"args": ["hyperliquid-mcp"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "your_private_key_here",
"HYPERLIQUID_USER_ADDRESS": "0x1234567890123456789012345678901234567890",
"HYPERLIQUID_TESTNET": "false"
},
"transport": "stdio"
}
}
}
```
### Alternative Configurations
#### Using uv directly:
```json
{
"mcpServers": {
"hyperliquid": {
"command": "uv",
"args": ["run", "--with", "hyperliquid-mcp", "hyperliquid-mcp"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "your_private_key_here",
"HYPERLIQUID_USER_ADDRESS": "0x1234567890123456789012345678901234567890",
"HYPERLIQUID_TESTNET": "false"
},
"transport": "stdio"
}
}
}
```
#### Local development:
```json
{
"mcpServers": {
"hyperliquid": {
"command": "uv",
"args": ["run", "hyperliquid-mcp"],
"cwd": "/path/to/hyperliquid-mcp",
"env": {
"HYPERLIQUID_PRIVATE_KEY": "your_private_key_here",
"HYPERLIQUID_USER_ADDRESS": "0x1234567890123456789012345678901234567890",
"HYPERLIQUID_TESTNET": "true"
},
"transport": "stdio"
}
}
}
```
## 🛠️ Available Tools
### 👤 Account Management (11 tools)
#### `get_positions`
Get current trading positions and margin information.
- **Input**: `user` (optional) - Ethereum address to query (defaults to `HYPERLIQUID_USER_ADDRESS` or wallet address)
- **Output**: Positions and margin summary data
#### `get_account_info`
Retrieve comprehensive account information including margin details.
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: Account information and margin summary
#### `update_leverage`
Modify leverage settings for a specific asset.
- **Input**: `asset`, `leverage` (1-100), `is_isolated` (boolean)
- **Output**: Leverage update confirmation
#### `transfer_between_spot_and_perp`
Transfer funds between spot and perpetual trading accounts.
- **Input**: `amount`, `to_perp` (boolean)
- **Output**: Transfer confirmation
#### `usd_transfer`
Transfer USDC to another wallet address.
- **Input**: `destination` (Ethereum address), `amount`
- **Output**: Transfer result
#### `withdraw`
Withdraw USDC to an external wallet.
- **Input**: `destination` (Ethereum address), `amount` (minimum $1.01)
- **Output**: Withdrawal confirmation
#### `get_spot_user_state`
Get spot trading account balances and state.
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: Spot account balances and state
#### `sub_account_transfer`
Transfer funds between main account and sub-accounts.
- **Input**: `sub_account` (address), `amount`, `is_deposit` (boolean)
- **Output**: Transfer confirmation
#### `get_user_portfolio`
Retrieve detailed portfolio information.
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: Portfolio data and analytics
#### `get_user_fees`
Get user's current fee structure and rates.
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: Fee information and tier details
### 📊 Market Data (8 tools)
#### `get_market_data`
Get current market data for a specific asset.
- **Input**: `asset` - Asset symbol (e.g., "BTC", "ETH")
- **Output**: Current price, volume, and market statistics
#### `get_all_mids_detailed`
Retrieve detailed market data for all available assets.
- **Input**: None
- **Output**: Comprehensive market data for all assets
#### `get_candle_data`
Get historical OHLCV candlestick data.
- **Input**: `asset`, `interval` (1m, 5m, 1h, 1d, etc.), `start_time`, `end_time`
- **Output**: Historical price candles
#### `get_l2_orderbook`
Get Level 2 order book depth data.
- **Input**: `asset`, `significant_figures` (optional, 1-10)
- **Output**: Bid/ask levels with quantities
#### `get_funding_rates`
Retrieve current and historical funding rates for perpetual contracts.
- **Input**: `asset` (optional), `include_history` (boolean), `start_time` (optional)
- **Output**: Funding rate data
#### `calculate_min_order_size`
Calculate minimum order size for an asset to meet value requirements.
- **Input**: `asset`, `min_value_usd` (default: $10)
- **Output**: Minimum order size calculation
#### `simulate_order`
Simulate order execution without placing actual order.
- **Input**: `asset`, `is_buy` (boolean), `size`, `price` (optional)
- **Output**: Simulation results and impact analysis
#### `get_user_fills_by_time`
Get user's trade fills within a specific time range.
- **Input**: `start_time`, `end_time` (optional), `user` (optional)
- **Output**: Trade execution history
### 📈 Order Management (10 tools)
#### `place_order`
Place a new trading order on the exchange.
- **Input**: Order details including:
- `asset` - Asset symbol
- `is_buy` - Order direction (boolean)
- `size` - Order quantity
- `order_type` - "market", "limit", or "trigger"
- `price` - Order price (required for limit/trigger)
- `time_in_force` - "GTC", "IOC", or "ALO"
- `reduce_only` - Reduce-only flag (boolean)
- `take_profit` - Take profit price (optional)
- `stop_loss` - Stop loss price (optional)
- **Output**: Order placement confirmation with order ID
#### `cancel_order`
Cancel an existing order.
- **Input**: `asset`, `order_id`
- **Output**: Cancellation confirmation
#### `modify_order`
Modify price, size, or time-in-force of an existing order.
- **Input**: `asset`, `order_id`, `new_price` (optional), `new_size` (optional), `new_time_in_force` (optional)
- **Output**: Modification confirmation
#### `get_open_orders`
Retrieve all currently open orders.
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: List of open orders with details
#### `get_order_status`
Check the status of a specific order.
- **Input**: `order_id`, `user` (optional)
- **Output**: Order status and execution details
#### `bulk_cancel_orders`
Cancel multiple orders in a single request.
- **Input**: `orders` - List of orders with asset and order_id
- **Output**: Bulk cancellation results
#### `cancel_all_orders`
Cancel all open orders, optionally filtered by asset.
- **Input**: `asset` (optional) - Filter by specific asset
- **Output**: Mass cancellation confirmation
#### `get_user_fills`
Get recent trade executions (fills).
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: Recent trade execution data
#### `get_historical_orders`
Retrieve historical order data.
- **Input**: `user` (optional) - Ethereum address to query
- **Output**: Historical order information
## 📝 Usage Examples
### Basic Market Data Query
```python
# Get current BTC market data
result = await get_market_data(GetMarketDataRequest(asset="BTC"))
print(f"BTC Price: ${result['price']}")
```
### Place a Limit Order
```python
# Place a limit buy order for 1 ETH at $2000
order_request = PlaceOrderRequest(
asset="ETH",
is_buy=True,
size=1.0,
order_type=OrderType.LIMIT,
price=2000.0,
time_in_force=TimeInForce.GTC
)
result = await place_order(order_request)
print(f"Order placed with ID: {result['orderId']}")
```
### Check Account Positions
```python
# Get current positions
positions = await get_positions(UserAddressRequest())
for position in positions['positions']:
print(f"{position['asset']}: {position['size']} @ ${position['avgPrice']}")
```
### Get Historical Candles
```python
# Get 1-hour candles for ETH from last 24 hours
import time
end_time = int(time.time() * 1000)
start_time = end_time - (24 * 60 * 60 * 1000) # 24 hours ago
candles = await get_candle_data(GetCandleDataRequest(
asset="ETH",
interval=CandleInterval.ONE_HOUR,
start_time=start_time,
end_time=end_time
))
```
## 🔒 Security Best Practices
1. **Private Key Management**:
- Store private keys securely using environment variables
- Never commit private keys to version control
- Use hardware wallets for maximum security
2. **API Usage**:
- Always validate order parameters before submission
- Use `simulate_order` to test order logic
- Implement proper error handling
3. **Risk Management**:
- Set appropriate position sizes
- Use stop-loss orders for risk control
- Monitor account balances and margins
## 🧪 Testing
The project includes comprehensive tests covering all tools:
```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=hyperliquid_mcp
# Run specific test categories
uv run pytest tests/test_server.py::TestAccountTools
```
## 🔧 Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/yourusername/hyperliquid-mcp.git
cd hyperliquid-mcp
# Install with development dependencies
uv sync --dev
# Run tests
uv run pytest
# Format code
uv run black src/ tests/
uv run isort src/ tests/
# Type checking
uv run mypy src/
```
### Project Structure
```
hyperliquid-mcp/
├── src/hyperliquid_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server implementation
│ ├── client.py # Hyperliquid API client
│ └── models.py # Pydantic models
├── tests/
│ ├── test_server.py # Tool function tests
│ └── test_mcp_integration.py # MCP integration tests
├── pyproject.toml # Project configuration
└── README.md
```
## 📚 API Reference
### Order Types
- **market**: Execute immediately at current market price
- **limit**: Execute only at specified price or better
- **trigger**: Stop/trigger order that becomes market order when triggered
### Time in Force
- **GTC** (Good Till Cancelled): Order remains active until filled or cancelled
- **IOC** (Immediate or Cancel): Fill immediately or cancel unfilled portion
- **ALO** (Add Liquidity Only): Only add liquidity, don't take from order book
### Candle Intervals
Supported intervals: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M`
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ⚠️ Disclaimer
This software is provided for educational and informational purposes only. Trading cryptocurrencies involves substantial risk and may result in significant financial losses. The authors are not responsible for any trading losses incurred through the use of this software. Always conduct your own research and consider consulting with a qualified financial advisor before making trading decisions.
## 🔗 Links
- [Hyperliquid Exchange](https://hyperliquid.xyz/)
- [Hyperliquid Documentation](https://hyperliquid.gitbook.io/hyperliquid-docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
- [Claude Desktop](https://claude.ai/desktop)
## 📞 Support
For questions, issues, or contributions:
- Open an issue on GitHub
- Check the [Hyperliquid Discord](https://discord.gg/hyperliquid) for community support
- Review the comprehensive test suite for usage examples
Raw data
{
"_id": null,
"home_page": null,
"name": "hyperliquid-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "crypto, defi, exchange, hyperliquid, mcp, trading",
"author": null,
"author_email": "Minh DOAN <midogax272@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b2/bb/aa834aecf093f8972d02ff60bab8572d606c05d9a35326e3062fb4a50ef4/hyperliquid_mcp-0.1.5.tar.gz",
"platform": null,
"description": "# Hyperliquid MCP Server\n\nA Model Context Protocol (MCP) server that provides comprehensive tools for interacting with the Hyperliquid decentralized exchange. This server enables AI assistants to perform trading operations, manage accounts, and retrieve market data through a standardized interface.\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/jlowin/fastmcp)\n\n## \ud83d\ude80 Features\n\n- **29 Trading Tools** - Complete coverage of Hyperliquid's API\n- **Account Management** - Positions, balances, transfers, and leverage control\n- **Order Management** - Place, cancel, modify orders with advanced features\n- **Market Data** - Real-time prices, orderbooks, candles, and funding rates\n- **Risk Management** - Order simulation and validation\n- **Type Safety** - Full Pydantic validation for all inputs\n- **Error Handling** - Comprehensive error reporting and logging\n\n## \ud83d\udce6 Installation\n\n### Using uvx (Recommended)\n\n```bash\nuvx hyperliquid-mcp\n```\n\n### Using uv\n\n```bash\nuv add hyperliquid-mcp\nuv run hyperliquid-mcp\n```\n\n### Using pip\n\n```bash\npip install hyperliquid-mcp\nhyperliquid-mcp\n```\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\nConfigure the following environment variables:\n\n```bash\n# Required for trading operations\nexport HYPERLIQUID_PRIVATE_KEY=\"your_private_key_here\"\n\n# Optional: Specify a different user address for queries (defaults to wallet address)\nexport HYPERLIQUID_USER_ADDRESS=\"0x1234567890123456789012345678901234567890\"\n\n# Optional: Use testnet instead of mainnet (default: false)\nexport HYPERLIQUID_TESTNET=\"true\"\n```\n\n> \u26a0\ufe0f **Security Warning**: Never share your private key. The server will warn if the key is missing but will still start in read-only mode for market data.\n\n#### Environment Variable Details\n\n- **`HYPERLIQUID_PRIVATE_KEY`** (Required for trading): Your wallet's private key for signing transactions\n- **`HYPERLIQUID_USER_ADDRESS`** (Optional): Ethereum address to query data for. If not set, uses the address derived from your private key\n- **`HYPERLIQUID_TESTNET`** (Optional): Set to `\"true\"` to use Hyperliquid's testnet for development and testing\n\n### \ud83d\udc64 User Address Configuration\n\nThe server supports querying data for different users:\n\n- **Default behavior**: Uses the address derived from your `HYPERLIQUID_PRIVATE_KEY`\n- **Custom user**: Set `HYPERLIQUID_USER_ADDRESS` to query a different address\n- **Tool-level override**: Many tools accept a `user` parameter to query specific addresses\n\n**Use cases:**\n- Monitor multiple accounts from one server instance\n- Query public data for other traders (positions, fills, etc.)\n- Portfolio management for multiple wallets\n- Analytics and research on other users' trading activity\n\n### \ud83e\uddea Testnet Configuration\n\nFor development and testing, you can use Hyperliquid's testnet:\n\n1. **Enable testnet mode** by setting `HYPERLIQUID_TESTNET=true`\n2. **Get testnet tokens** from the [Hyperliquid testnet faucet](https://app.hyperliquid-testnet.xyz/faucet)\n3. **Use testnet-specific addresses** - testnet has separate contracts and addresses\n4. **Test safely** - All trades execute on testnet without real financial risk\n\n> \ud83d\udca1 **Tip**: Always test your trading strategies on testnet before using real funds on mainnet.\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"hyperliquid\": {\n \"command\": \"uvx\",\n \"args\": [\"hyperliquid-mcp\"],\n \"env\": {\n \"HYPERLIQUID_PRIVATE_KEY\": \"your_private_key_here\",\n \"HYPERLIQUID_USER_ADDRESS\": \"0x1234567890123456789012345678901234567890\",\n \"HYPERLIQUID_TESTNET\": \"false\"\n },\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Alternative Configurations\n\n#### Using uv directly:\n```json\n{\n \"mcpServers\": {\n \"hyperliquid\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--with\", \"hyperliquid-mcp\", \"hyperliquid-mcp\"],\n \"env\": {\n \"HYPERLIQUID_PRIVATE_KEY\": \"your_private_key_here\",\n \"HYPERLIQUID_USER_ADDRESS\": \"0x1234567890123456789012345678901234567890\",\n \"HYPERLIQUID_TESTNET\": \"false\"\n },\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n#### Local development:\n```json\n{\n \"mcpServers\": {\n \"hyperliquid\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"hyperliquid-mcp\"],\n \"cwd\": \"/path/to/hyperliquid-mcp\",\n \"env\": {\n \"HYPERLIQUID_PRIVATE_KEY\": \"your_private_key_here\",\n \"HYPERLIQUID_USER_ADDRESS\": \"0x1234567890123456789012345678901234567890\",\n \"HYPERLIQUID_TESTNET\": \"true\"\n },\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f Available Tools\n\n### \ud83d\udc64 Account Management (11 tools)\n\n#### `get_positions`\nGet current trading positions and margin information.\n- **Input**: `user` (optional) - Ethereum address to query (defaults to `HYPERLIQUID_USER_ADDRESS` or wallet address)\n- **Output**: Positions and margin summary data\n\n#### `get_account_info`\nRetrieve comprehensive account information including margin details.\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: Account information and margin summary\n\n#### `update_leverage`\nModify leverage settings for a specific asset.\n- **Input**: `asset`, `leverage` (1-100), `is_isolated` (boolean)\n- **Output**: Leverage update confirmation\n\n#### `transfer_between_spot_and_perp`\nTransfer funds between spot and perpetual trading accounts.\n- **Input**: `amount`, `to_perp` (boolean)\n- **Output**: Transfer confirmation\n\n#### `usd_transfer`\nTransfer USDC to another wallet address.\n- **Input**: `destination` (Ethereum address), `amount`\n- **Output**: Transfer result\n\n#### `withdraw`\nWithdraw USDC to an external wallet.\n- **Input**: `destination` (Ethereum address), `amount` (minimum $1.01)\n- **Output**: Withdrawal confirmation\n\n#### `get_spot_user_state`\nGet spot trading account balances and state.\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: Spot account balances and state\n\n#### `sub_account_transfer`\nTransfer funds between main account and sub-accounts.\n- **Input**: `sub_account` (address), `amount`, `is_deposit` (boolean)\n- **Output**: Transfer confirmation\n\n#### `get_user_portfolio`\nRetrieve detailed portfolio information.\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: Portfolio data and analytics\n\n#### `get_user_fees`\nGet user's current fee structure and rates.\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: Fee information and tier details\n\n### \ud83d\udcca Market Data (8 tools)\n\n#### `get_market_data`\nGet current market data for a specific asset.\n- **Input**: `asset` - Asset symbol (e.g., \"BTC\", \"ETH\")\n- **Output**: Current price, volume, and market statistics\n\n#### `get_all_mids_detailed`\nRetrieve detailed market data for all available assets.\n- **Input**: None\n- **Output**: Comprehensive market data for all assets\n\n#### `get_candle_data`\nGet historical OHLCV candlestick data.\n- **Input**: `asset`, `interval` (1m, 5m, 1h, 1d, etc.), `start_time`, `end_time`\n- **Output**: Historical price candles\n\n#### `get_l2_orderbook`\nGet Level 2 order book depth data.\n- **Input**: `asset`, `significant_figures` (optional, 1-10)\n- **Output**: Bid/ask levels with quantities\n\n#### `get_funding_rates`\nRetrieve current and historical funding rates for perpetual contracts.\n- **Input**: `asset` (optional), `include_history` (boolean), `start_time` (optional)\n- **Output**: Funding rate data\n\n#### `calculate_min_order_size`\nCalculate minimum order size for an asset to meet value requirements.\n- **Input**: `asset`, `min_value_usd` (default: $10)\n- **Output**: Minimum order size calculation\n\n#### `simulate_order`\nSimulate order execution without placing actual order.\n- **Input**: `asset`, `is_buy` (boolean), `size`, `price` (optional)\n- **Output**: Simulation results and impact analysis\n\n#### `get_user_fills_by_time`\nGet user's trade fills within a specific time range.\n- **Input**: `start_time`, `end_time` (optional), `user` (optional)\n- **Output**: Trade execution history\n\n### \ud83d\udcc8 Order Management (10 tools)\n\n#### `place_order`\nPlace a new trading order on the exchange.\n- **Input**: Order details including:\n - `asset` - Asset symbol\n - `is_buy` - Order direction (boolean)\n - `size` - Order quantity\n - `order_type` - \"market\", \"limit\", or \"trigger\"\n - `price` - Order price (required for limit/trigger)\n - `time_in_force` - \"GTC\", \"IOC\", or \"ALO\"\n - `reduce_only` - Reduce-only flag (boolean)\n - `take_profit` - Take profit price (optional)\n - `stop_loss` - Stop loss price (optional)\n- **Output**: Order placement confirmation with order ID\n\n#### `cancel_order`\nCancel an existing order.\n- **Input**: `asset`, `order_id`\n- **Output**: Cancellation confirmation\n\n#### `modify_order`\nModify price, size, or time-in-force of an existing order.\n- **Input**: `asset`, `order_id`, `new_price` (optional), `new_size` (optional), `new_time_in_force` (optional)\n- **Output**: Modification confirmation\n\n#### `get_open_orders`\nRetrieve all currently open orders.\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: List of open orders with details\n\n#### `get_order_status`\nCheck the status of a specific order.\n- **Input**: `order_id`, `user` (optional)\n- **Output**: Order status and execution details\n\n#### `bulk_cancel_orders`\nCancel multiple orders in a single request.\n- **Input**: `orders` - List of orders with asset and order_id\n- **Output**: Bulk cancellation results\n\n#### `cancel_all_orders`\nCancel all open orders, optionally filtered by asset.\n- **Input**: `asset` (optional) - Filter by specific asset\n- **Output**: Mass cancellation confirmation\n\n#### `get_user_fills`\nGet recent trade executions (fills).\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: Recent trade execution data\n\n#### `get_historical_orders`\nRetrieve historical order data.\n- **Input**: `user` (optional) - Ethereum address to query\n- **Output**: Historical order information\n\n## \ud83d\udcdd Usage Examples\n\n### Basic Market Data Query\n```python\n# Get current BTC market data\nresult = await get_market_data(GetMarketDataRequest(asset=\"BTC\"))\nprint(f\"BTC Price: ${result['price']}\")\n```\n\n### Place a Limit Order\n```python\n# Place a limit buy order for 1 ETH at $2000\norder_request = PlaceOrderRequest(\n asset=\"ETH\",\n is_buy=True,\n size=1.0,\n order_type=OrderType.LIMIT,\n price=2000.0,\n time_in_force=TimeInForce.GTC\n)\nresult = await place_order(order_request)\nprint(f\"Order placed with ID: {result['orderId']}\")\n```\n\n### Check Account Positions\n```python\n# Get current positions\npositions = await get_positions(UserAddressRequest())\nfor position in positions['positions']:\n print(f\"{position['asset']}: {position['size']} @ ${position['avgPrice']}\")\n```\n\n### Get Historical Candles\n```python\n# Get 1-hour candles for ETH from last 24 hours\nimport time\nend_time = int(time.time() * 1000)\nstart_time = end_time - (24 * 60 * 60 * 1000) # 24 hours ago\n\ncandles = await get_candle_data(GetCandleDataRequest(\n asset=\"ETH\",\n interval=CandleInterval.ONE_HOUR,\n start_time=start_time,\n end_time=end_time\n))\n```\n\n## \ud83d\udd12 Security Best Practices\n\n1. **Private Key Management**:\n - Store private keys securely using environment variables\n - Never commit private keys to version control\n - Use hardware wallets for maximum security\n\n2. **API Usage**:\n - Always validate order parameters before submission\n - Use `simulate_order` to test order logic\n - Implement proper error handling\n\n3. **Risk Management**:\n - Set appropriate position sizes\n - Use stop-loss orders for risk control\n - Monitor account balances and margins\n\n## \ud83e\uddea Testing\n\nThe project includes comprehensive tests covering all tools:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=hyperliquid_mcp\n\n# Run specific test categories\nuv run pytest tests/test_server.py::TestAccountTools\n```\n\n## \ud83d\udd27 Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/hyperliquid-mcp.git\ncd hyperliquid-mcp\n\n# Install with development dependencies\nuv sync --dev\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run black src/ tests/\nuv run isort src/ tests/\n\n# Type checking\nuv run mypy src/\n```\n\n### Project Structure\n\n```\nhyperliquid-mcp/\n\u251c\u2500\u2500 src/hyperliquid_mcp/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 server.py # MCP server implementation\n\u2502 \u251c\u2500\u2500 client.py # Hyperliquid API client\n\u2502 \u2514\u2500\u2500 models.py # Pydantic models\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_server.py # Tool function tests\n\u2502 \u2514\u2500\u2500 test_mcp_integration.py # MCP integration tests\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md\n```\n\n## \ud83d\udcda API Reference\n\n### Order Types\n- **market**: Execute immediately at current market price\n- **limit**: Execute only at specified price or better\n- **trigger**: Stop/trigger order that becomes market order when triggered\n\n### Time in Force\n- **GTC** (Good Till Cancelled): Order remains active until filled or cancelled\n- **IOC** (Immediate or Cancel): Fill immediately or cancel unfilled portion\n- **ALO** (Add Liquidity Only): Only add liquidity, don't take from order book\n\n### Candle Intervals\nSupported intervals: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M`\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \u26a0\ufe0f Disclaimer\n\nThis software is provided for educational and informational purposes only. Trading cryptocurrencies involves substantial risk and may result in significant financial losses. The authors are not responsible for any trading losses incurred through the use of this software. Always conduct your own research and consider consulting with a qualified financial advisor before making trading decisions.\n\n## \ud83d\udd17 Links\n\n- [Hyperliquid Exchange](https://hyperliquid.xyz/)\n- [Hyperliquid Documentation](https://hyperliquid.gitbook.io/hyperliquid-docs)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [FastMCP Framework](https://github.com/jlowin/fastmcp)\n- [Claude Desktop](https://claude.ai/desktop)\n\n## \ud83d\udcde Support\n\nFor questions, issues, or contributions:\n- Open an issue on GitHub\n- Check the [Hyperliquid Discord](https://discord.gg/hyperliquid) for community support\n- Review the comprehensive test suite for usage examples",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Hyperliquid MCP Server\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A server that exposes a set of tools for interacting with the Hyperliquid decentralized exchange. It simplifies trading operations by providing a high-level API for placing, canceling, and modifying orders, as well as managing account settings and retrieving market data.",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/midodimori/hyperliquid-mcp#readme",
"Homepage": "https://github.com/midodimori/hyperliquid-mcp",
"Issues": "https://github.com/midodimori/hyperliquid-mcp/issues",
"Repository": "https://github.com/midodimori/hyperliquid-mcp"
},
"split_keywords": [
"crypto",
" defi",
" exchange",
" hyperliquid",
" mcp",
" trading"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dc7ef477ad1354cb1af864eee1fead87248c867cfee6fb1682b65c9934ef7e68",
"md5": "1db5dc2e37edc236ee19debf55583d8b",
"sha256": "1819878438f3df37d6aef09098fa34700ab400a2ee782c95f836c2d9141b42a4"
},
"downloads": -1,
"filename": "hyperliquid_mcp-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1db5dc2e37edc236ee19debf55583d8b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 20987,
"upload_time": "2025-07-29T02:24:14",
"upload_time_iso_8601": "2025-07-29T02:24:14.157057Z",
"url": "https://files.pythonhosted.org/packages/dc/7e/f477ad1354cb1af864eee1fead87248c867cfee6fb1682b65c9934ef7e68/hyperliquid_mcp-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b2bbaa834aecf093f8972d02ff60bab8572d606c05d9a35326e3062fb4a50ef4",
"md5": "7faad8ab4f7c5f39e33cf0f0d2bb1c98",
"sha256": "18df7f0e3fa94cae3aa115ee2a425e3662a651e6a28c7983b20961c5216e2f0d"
},
"downloads": -1,
"filename": "hyperliquid_mcp-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "7faad8ab4f7c5f39e33cf0f0d2bb1c98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 107047,
"upload_time": "2025-07-29T02:24:15",
"upload_time_iso_8601": "2025-07-29T02:24:15.882637Z",
"url": "https://files.pythonhosted.org/packages/b2/bb/aa834aecf093f8972d02ff60bab8572d606c05d9a35326e3062fb4a50ef4/hyperliquid_mcp-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 02:24:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "midodimori",
"github_project": "hyperliquid-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hyperliquid-mcp"
}
