| Name | hl-mcp-server JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Model Context Protocol (MCP) server for Hyperliquid DEX trading |
| upload_time | 2025-08-03 16:36:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
hyperliquid
mcp
trading
defi
fastmcp
|
| 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 for interacting with [Hyperliquid DEX](https://hyperliquid.xyz/).
## Features
- **Order Management**: Place, modify, and cancel orders with support for both limit and market orders
- **USD-Based Sizing**: Specify order sizes in USD amounts for easier position sizing
- **Leverage Control**: Set and modify leverage for perpetual positions
- **Account Analytics**: Comprehensive P&L tracking, position monitoring, and balance queries
- **Market Data**: Access perpetual and spot market metadata
- **Flexible Authentication**: Separate accounts for trading operations and data queries
## Installation
### From PyPI (Recommended)
```bash
pip install -r requirements.txt
```
### From Source
```bash
git clone https://github.com/OmChillure/hyperliquid
cd hyperliquid_mcp
pip install -e .
```
## Quick Start
### 1. Running with uv/pip
If you prefer to run the server directly:
```json
{
"mcpServers": {
"hyperliquid": {
"command": "python/uvx",
"args": ["/path/to/your/hyperliquid/server.py"],
"env": {
"HYPERLIQUID_MAIN_ACCOUNT_ADDRESS": "",
"HYPERLIQUID_API_ACCOUNT_ADDRESS": "",
"HYPERLIQUID_API_ACCOUNT_PRIVATE_KEY": ""
}
}
}
}
```
## Available Tools
### Trading Operations
- **`placeOrder`**: Place limit or market orders with USD-based sizing support
- **`modifyOrder`**: Modify existing orders
- **`cancelOrder`**: Cancel orders by ID or client order ID
### Account Management
- **`getAccountState`**: Get comprehensive account information including P&L, positions, and balances
- **`getUserTradeHistory`**: Retrieve trade history and fill data
- **`getUserSpotBalances`**: Query spot token balances
### Market Data
- **`getPerpetualsMeta`**: Get metadata for all perpetual markets
- **`getSpotMeta`**: Get metadata for all spot markets and tokens
## Usage Examples
### Place a Market Order
```python
# Buy $100 worth of ETH at market price
await placeOrder(
coin="ETH",
is_buy=True,
usd_amount=100.0,
order_type="market"
)
```
### Place a Limit Order with Leverage
```python
# Place a limit buy order with 10x leverage
await placeOrder(
coin="BTC",
is_buy=True,
size=0.1,
price=45000.0,
order_type="limit",
leverage=10,
is_cross=False
)
```
### Check Account State
```python
# Get comprehensive account information
account_info = await getAccountState()
print(f"Total PnL: ${account_info['pnl_overview']['total_pnl']}")
print(f"Account Value: ${account_info['pnl_overview']['account_value']}")
```
## Security Architecture
This MCP server uses a dual-account architecture for enhanced security:
- **Main Account**: Your primary trading account that holds funds. Used only for read-only operations.
- **API Account**: A separate account used exclusively for signing transactions. Should have minimal or no funds.
This separation means:
1. Your main trading funds are never directly exposed
2. The API account can be easily rotated if compromised
3. You can grant specific permissions to the API account via Hyperliquid's interface
## Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `HYPERLIQUID_MAIN_ACCOUNT_ADDRESS` | Your main trading account address | Yes |
| `HYPERLIQUID_API_ACCOUNT_ADDRESS` | API account address for signing | Yes |
| `HYPERLIQUID_API_ACCOUNT_PRIVATE_KEY` | Private key for API account | Yes |
| `HYPERLIQUID_BASE_URL` | Hyperliquid API endpoint | No (defaults to mainnet) |
## Development
### Setting up for Development
```bash
git clone https://github.com/yourusername/hyperliquid-mcp
cd hyperliquid-mcp
pip install -e ".[dev]"
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "hl-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "hyperliquid, mcp, trading, defi, fastmcp",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a8/21/4f12c88095dd46aa00246327a327f71d0773b679930dbe7c84c58f849386/hl_mcp_server-0.1.0.tar.gz",
"platform": null,
"description": "# Hyperliquid MCP Server\r\n\r\nA [Model Context Protocol (MCP)] server for interacting with [Hyperliquid DEX](https://hyperliquid.xyz/).\r\n\r\n## Features\r\n\r\n- **Order Management**: Place, modify, and cancel orders with support for both limit and market orders\r\n- **USD-Based Sizing**: Specify order sizes in USD amounts for easier position sizing\r\n- **Leverage Control**: Set and modify leverage for perpetual positions\r\n- **Account Analytics**: Comprehensive P&L tracking, position monitoring, and balance queries\r\n- **Market Data**: Access perpetual and spot market metadata\r\n- **Flexible Authentication**: Separate accounts for trading operations and data queries\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install -r requirements.txt\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/OmChillure/hyperliquid\r\ncd hyperliquid_mcp\r\npip install -e .\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Running with uv/pip\r\n\r\nIf you prefer to run the server directly:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"hyperliquid\": {\r\n \"command\": \"python/uvx\",\r\n \"args\": [\"/path/to/your/hyperliquid/server.py\"],\r\n \"env\": {\r\n \"HYPERLIQUID_MAIN_ACCOUNT_ADDRESS\": \"\",\r\n \"HYPERLIQUID_API_ACCOUNT_ADDRESS\": \"\",\r\n \"HYPERLIQUID_API_ACCOUNT_PRIVATE_KEY\": \"\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n## Available Tools\r\n\r\n### Trading Operations\r\n\r\n- **`placeOrder`**: Place limit or market orders with USD-based sizing support\r\n- **`modifyOrder`**: Modify existing orders \r\n- **`cancelOrder`**: Cancel orders by ID or client order ID\r\n\r\n### Account Management \r\n\r\n- **`getAccountState`**: Get comprehensive account information including P&L, positions, and balances\r\n- **`getUserTradeHistory`**: Retrieve trade history and fill data\r\n- **`getUserSpotBalances`**: Query spot token balances\r\n\r\n### Market Data\r\n\r\n- **`getPerpetualsMeta`**: Get metadata for all perpetual markets\r\n- **`getSpotMeta`**: Get metadata for all spot markets and tokens\r\n\r\n## Usage Examples\r\n\r\n### Place a Market Order\r\n\r\n```python\r\n# Buy $100 worth of ETH at market price\r\nawait placeOrder(\r\n coin=\"ETH\",\r\n is_buy=True,\r\n usd_amount=100.0,\r\n order_type=\"market\"\r\n)\r\n```\r\n\r\n### Place a Limit Order with Leverage\r\n\r\n```python\r\n# Place a limit buy order with 10x leverage\r\nawait placeOrder(\r\n coin=\"BTC\", \r\n is_buy=True,\r\n size=0.1,\r\n price=45000.0,\r\n order_type=\"limit\",\r\n leverage=10,\r\n is_cross=False\r\n)\r\n```\r\n\r\n### Check Account State\r\n\r\n```python\r\n# Get comprehensive account information\r\naccount_info = await getAccountState()\r\nprint(f\"Total PnL: ${account_info['pnl_overview']['total_pnl']}\")\r\nprint(f\"Account Value: ${account_info['pnl_overview']['account_value']}\")\r\n```\r\n\r\n## Security Architecture\r\n\r\nThis MCP server uses a dual-account architecture for enhanced security:\r\n\r\n- **Main Account**: Your primary trading account that holds funds. Used only for read-only operations.\r\n- **API Account**: A separate account used exclusively for signing transactions. Should have minimal or no funds.\r\n\r\nThis separation means:\r\n1. Your main trading funds are never directly exposed\r\n2. The API account can be easily rotated if compromised\r\n3. You can grant specific permissions to the API account via Hyperliquid's interface\r\n\r\n## Environment Variables\r\n\r\n| Variable | Description | Required |\r\n|----------|-------------|----------|\r\n| `HYPERLIQUID_MAIN_ACCOUNT_ADDRESS` | Your main trading account address | Yes |\r\n| `HYPERLIQUID_API_ACCOUNT_ADDRESS` | API account address for signing | Yes |\r\n| `HYPERLIQUID_API_ACCOUNT_PRIVATE_KEY` | Private key for API account | Yes |\r\n| `HYPERLIQUID_BASE_URL` | Hyperliquid API endpoint | No (defaults to mainnet) |\r\n\r\n## Development\r\n\r\n### Setting up for Development\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/hyperliquid-mcp\r\ncd hyperliquid-mcp\r\npip install -e \".[dev]\"\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol (MCP) server for Hyperliquid DEX trading",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"hyperliquid",
" mcp",
" trading",
" defi",
" fastmcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "908db791694916132787be070ccb0068873b1fdcf58e314701e2b7ae3e45e248",
"md5": "3c2774ce77a5d6b5efdcdba96e5df359",
"sha256": "0b9c75f24413acd37a305e64c8a5073656b7de53bb6ff5c78faca85c3692c451"
},
"downloads": -1,
"filename": "hl_mcp_server-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c2774ce77a5d6b5efdcdba96e5df359",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9032,
"upload_time": "2025-08-03T16:36:44",
"upload_time_iso_8601": "2025-08-03T16:36:44.729679Z",
"url": "https://files.pythonhosted.org/packages/90/8d/b791694916132787be070ccb0068873b1fdcf58e314701e2b7ae3e45e248/hl_mcp_server-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a8214f12c88095dd46aa00246327a327f71d0773b679930dbe7c84c58f849386",
"md5": "ec38710e9ac4d8b71420b81bdf8fa7ce",
"sha256": "b3029c79d9edec36a31c429b2c70f40c76d1f83cb659dcad1dbe1865dda0bb26"
},
"downloads": -1,
"filename": "hl_mcp_server-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ec38710e9ac4d8b71420b81bdf8fa7ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 8262,
"upload_time": "2025-08-03T16:36:46",
"upload_time_iso_8601": "2025-08-03T16:36:46.204532Z",
"url": "https://files.pythonhosted.org/packages/a8/21/4f12c88095dd46aa00246327a327f71d0773b679930dbe7c84c58f849386/hl_mcp_server-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 16:36:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hl-mcp-server"
}
