UBOS Asset Marketplace: Hyperliquid MCP Server v9 - Empowering AI-Driven Trading

In the rapidly evolving landscape of decentralized finance (DeFi), integrating Artificial Intelligence (AI) has become paramount for achieving optimal trading strategies, efficient market analysis, and automated decision-making. The UBOS Asset Marketplace proudly presents the Hyperliquid MCP (Model Context Protocol) Server v9, a comprehensive solution designed to bridge the gap between AI Agents and the Hyperliquid exchange, enabling seamless interaction and execution of sophisticated trading algorithms.

What is an MCP Server?

At its core, an MCP Server serves as a vital intermediary, translating complex data and functionalities into a standardized format that AI models can readily understand and utilize. MCP stands for Model Context Protocol. It’s an open protocol that standardizes how applications provide context to LLMs. In the context of Hyperliquid, the MCP Server acts as a wrapper around the Hyperliquid SDK, exposing its full suite of trading capabilities to AI assistants. This allows AI agents to access real-time market data, execute trades, manage positions, and perform a wide range of other operations on the Hyperliquid exchange.

Why Hyperliquid MCP Server?

Hyperliquid is a cutting-edge decentralized exchange known for its high-speed performance, advanced order types, and comprehensive suite of trading tools. By leveraging the Hyperliquid MCP Server, UBOS empowers AI agents to tap into the full potential of this powerful platform, enabling them to:

• Automate Trading Strategies: Develop and deploy sophisticated trading algorithms that react instantly to market changes.
• Access Real-Time Market Data: Obtain up-to-the-second market data, including prices, order books, and historical candle data, to inform trading decisions.
• Manage Positions Efficiently: Automate position management tasks, such as adjusting leverage, setting stop-loss orders, and closing positions.
• Optimize Trading Performance: Fine-tune trading strategies based on historical data and real-time market conditions.

Key Features of the Hyperliquid MCP Server v9

The Hyperliquid MCP Server v9 is packed with features designed to provide a seamless and efficient trading experience for AI agents. Here’s a detailed look at its capabilities:

1. Comprehensive API Coverage

• Complete Hyperliquid SDK Implementation: The server offers a complete implementation of all Hyperliquid SDK APIs for both spot and futures trading. This ensures that AI agents have access to the full range of trading capabilities offered by the exchange.
• Market Data Retrieval: AI agents can retrieve real-time market data, including prices, order books, and historical candle data. This data is crucial for making informed trading decisions.
• Order Placement and Management: The server supports a wide range of order types, including market, limit, and trigger orders. AI agents can also manage existing orders, including canceling and modifying them.
• Position Management: AI agents can manage their positions, including adjusting leverage, setting stop-loss orders, and closing positions.
• Account Information and Balances: The server provides access to account information and balances, allowing AI agents to monitor their trading performance.
• Funding Rate Information: AI agents can retrieve funding rate information, which is essential for trading perpetual futures contracts.
• Transfers and Withdrawals: The server supports transfers and withdrawals, allowing AI agents to move funds in and out of the Hyperliquid exchange.
• Vault Management: AI agents can manage vaults, which are used to store and manage funds.
• Sub-Account Management: The server supports sub-account management, allowing AI agents to create and manage multiple trading accounts.
• Referral System Integration: AI agents can participate in the Hyperliquid referral system, earning rewards for referring new users.

2. Technical Features

• Proper Authentication: The server uses both private key and wallet address for authentication, ensuring that only authorized AI agents can access the Hyperliquid exchange.
• Comprehensive Error Handling and Validation: The server includes comprehensive error handling and validation, ensuring that AI agents receive clear and informative error messages.
• Real-Time Market Data Access: The server provides real-time market data access, allowing AI agents to react instantly to market changes.
• Client Order ID (Cloid) Support: The server supports client order IDs (cloid) for order tracking, allowing AI agents to easily track their orders.
• Testnet and Mainnet Support: The server supports both testnet and mainnet, allowing AI agents to test their strategies before deploying them on the live exchange.

3. Identified APIs and Implementation

The Hyperliquid MCP Server v9 provides a comprehensive suite of APIs that cover all aspects of trading on the Hyperliquid exchange. These APIs are meticulously mapped to the Hyperliquid SDK, ensuring seamless integration and optimal performance.

Market Data APIs

• getAllMids: Get all mid prices for all available cryptocurrencies. Direct mapping to SDK’s info.getAllMids().
• getL2Book: Get order book data for a symbol. Direct mapping to SDK’s info.getL2Book().
• getCandleSnapshot: Get historical candle data. Direct mapping to SDK’s info.getCandleSnapshot().
• getMetaAndAssetCtxs: Get metadata and asset contexts for perpetual futures. Direct mapping to SDK’s info.perpetuals.getMetaAndAssetCtxs().
• getSpotMetaAndAssetCtxs: Get metadata and asset contexts for spot markets. Direct mapping to SDK’s info.spot.getSpotMetaAndAssetCtxs().

Account Information APIs

• getClearinghouseState: Get perpetual futures account state. Direct mapping to SDK’s info.perpetuals.getClearinghouseState().
• getSpotClearinghouseState: Get spot account state. Direct mapping to SDK’s info.spot.getSpotClearinghouseState().
• getUserOpenOrders: Get open orders. Direct mapping to SDK’s info.getUserOpenOrders().
• getUserFills: Get trade fills. Direct mapping to SDK’s info.getUserFills().
• getUserFillsByTime: Get trade fills by time range. Direct mapping to SDK’s info.getUserFillsByTime().
• getUserFunding: Get funding payments. Direct mapping to SDK’s info.perpetuals.getUserFunding().
• getFundingHistory: Get funding rate history. Direct mapping to SDK’s info.perpetuals.getFundingHistory().
• getPredictedFundings: Get predicted funding rates. Direct mapping to SDK’s info.perpetuals.getPredictedFundings().

Order Management APIs

• placeOrder: Place an order (market, limit, trigger). Direct mapping to SDK’s exchange.placeOrder().
• placeTwapOrder: Place a TWAP order. Direct mapping to SDK’s exchange.placeTwapOrder().
• cancelOrder: Cancel an order. Direct mapping to SDK’s exchange.cancelOrder().
• cancelOrderByCloid: Cancel an order by client order ID. Direct mapping to SDK’s exchange.cancelOrderByCloid().
• cancelTwapOrder: Cancel a TWAP order. Direct mapping to SDK’s exchange.cancelTwapOrder().
• modifyOrder: Modify an existing order. Direct mapping to SDK’s exchange.modifyOrder().

Position Management APIs

• updateLeverage: Update leverage for a symbol. Direct mapping to SDK’s exchange.updateLeverage().
• updateIsolatedMargin: Update isolated margin for a position. Direct mapping to SDK’s exchange.updateIsolatedMargin().
• marketClose: Close a position with a market order. Implemented via SDK’s custom.marketClose().
• closeAllPositions: Close all positions. Implemented via SDK’s custom.closeAllPositions().

Transfer and Withdrawal APIs

• usdTransfer: Transfer USDC to another wallet. Direct mapping to SDK’s exchange.usdTransfer().
• initiateWithdrawal: Withdraw USDC to Arbitrum. Direct mapping to SDK’s exchange.initiateWithdrawal().
• spotTransfer: Transfer spot assets to another wallet. Direct mapping to SDK’s exchange.spotTransfer().
• transferBetweenSpotAndPerp: Transfer between spot and perpetual accounts. Direct mapping to SDK’s exchange.transferBetweenSpotAndPerp().

Vault Management APIs

• createVault: Create a new vault. Direct mapping to SDK’s exchange.createVault().
• getVaultDetails: Get vault details. Direct mapping to SDK’s info.getVaultDetails().
• vaultTransfer: Transfer funds between vault and wallet. Direct mapping to SDK’s exchange.vaultTransfer().
• vaultDistribute: Distribute funds from vault to followers. Direct mapping to SDK’s exchange.vaultDistribute().
• vaultModify: Modify vault configuration. Direct mapping to SDK’s exchange.vaultModify().

Sub-Account Management APIs

• createSubAccount: Create a new sub-account. Direct mapping to SDK’s exchange.createSubAccount().
• getSubAccounts: Get all sub-accounts. Direct mapping to SDK’s info.getSubAccounts().
• subAccountTransfer: Transfer funds between sub-accounts (perpetual). Direct mapping to SDK’s exchange.subAccountTransfer().
• subAccountSpotTransfer: Transfer spot assets between sub-accounts. Direct mapping to SDK’s exchange.subAccountSpotTransfer().

Miscellaneous APIs

• setReferrer: Set a referrer code. Direct mapping to SDK’s exchange.setReferrer().
• referral: Get referral information. Direct mapping to SDK’s info.referral().
• setDisplayName: Set display name for leaderboard. Direct mapping to SDK’s exchange.setDisplayName().
• getUserRole: Get the role of a user. Direct mapping to SDK’s info.getUserRole().
• approveAgent: Approve an agent to trade on behalf of the user. Direct mapping to SDK’s exchange.approveAgent().
• approveBuilderFee: Approve a builder fee. Direct mapping to SDK’s exchange.approveBuilderFee().

4. Authentication Implementation

Security is paramount in the Hyperliquid MCP Server v9. The server implements a robust authentication mechanism that utilizes both private key and wallet address to ensure that only authorized AI agents can access the Hyperliquid exchange.

• Private Key Authentication: The server accepts a private key via environment variable or configuration file. This private key is used to sign transactions and authenticate with the Hyperliquid API.
• Wallet Address Authentication: The server also accepts a wallet address, which is used for read-only operations. If a private key is provided but no wallet address, the server will derive the wallet address from the private key.
• Vault Address Support: For vault operations, the server also supports specifying a vault address.

Authentication validation is performed before executing any operation that requires it, ensuring that the user is properly authenticated before attempting to execute trades or access account information.

5. Error Handling and Validation

The Hyperliquid MCP Server v9 implements comprehensive error handling and validation to ensure the stability and reliability of the system.

• Client Validation: Before executing any operation, the server validates that the Hyperliquid client is initialized.
• Authentication Validation: For operations that require authentication, the server validates that the user is properly authenticated.
• Parameter Validation: The server validates all parameters before passing them to the SDK, ensuring that they are of the correct type and format.
• Error Handling: The server catches and handles all errors from the SDK, providing clear error messages to the user.
• Logging: The server logs all operations and errors, making it easier to debug issues.

6. Implementation Challenges and Special Considerations

Developing the Hyperliquid MCP Server v9 involved overcoming several implementation challenges and addressing special considerations to ensure optimal performance and reliability.

• Market Order Implementation: Hyperliquid’s API doesn’t have a direct “market order” endpoint. Instead, market orders are implemented as aggressive limit orders with Immediate-or-Cancel (IOC) time-in-force. To ensure execution, we apply a slippage factor to the current price.
• Spot Market Symbol Handling: Spot market symbols in Hyperliquid have a “-SPOT” suffix. The MCP server handles this transparently, adding the suffix when needed.
• Order Response Parsing: The response format from the Hyperliquid API for order placement is complex and requires careful parsing to extract the order ID.
• Numeric Value Handling: The Hyperliquid API often returns numeric values as strings. The MCP server converts these to numbers for easier consumption.
• WebSocket Support: The Hyperliquid SDK supports WebSocket connections for real-time data. The MCP server initializes the client with WebSocket support enabled.

Getting Started with the Hyperliquid MCP Server v9

To get started with the Hyperliquid MCP Server v9, you will need to have the following prerequisites:

• Node.js (v14 or higher)
• A Hyperliquid account
• An Ethereum private key for authentication (required for trading)
• Your wallet address (required for trading)

Configuration

The server can be configured using environment variables or a configuration file.

Environment Variables

• HYPERLIQUID_PRIVATE_KEY: Your Ethereum private key for authentication (required for trading)
• HYPERLIQUID_WALLET_ADDRESS: Your wallet address (required for trading)
• HYPERLIQUID_VAULT_ADDRESS: Your vault address (optional, for vault operations)
• HYPERLIQUID_TESTNET: Set to ‘true’ to use testnet, ‘false’ for mainnet (default: false)
• LOG_LEVEL: Logging level - ‘debug’, ‘info’, ‘warn’, or ‘error’ (default: ‘info’)

Configuration File

You can also create a .hyperliquid-config.json file in the same directory as the server with the following structure:

{ “privateKey”: “your-ethereum-private-key”, “walletAddress”: “your-wallet-address”, “vaultAddress”: “your-vault-address”, “testnet”: false, “logLevel”: “info”, “popularCoins”: [“BTC”, “ETH”, “SOL”, “AVAX”, “ARB”, “DOGE”, “LINK”, “MATIC”] }

Running the Server

To start the server, run the following command:

bash node hyperliquid-mcp-server-complete.js

UBOS: The Full-Stack AI Agent Development Platform

The Hyperliquid MCP Server v9 is a valuable asset within the UBOS ecosystem, a full-stack AI Agent Development Platform designed to empower businesses across all departments. UBOS simplifies the orchestration of AI Agents, seamlessly connects them with enterprise data, and provides the tools to build custom AI Agents with your LLM model and Multi-Agent Systems.

Key Benefits of UBOS:

• Streamlined AI Agent Orchestration: UBOS provides a centralized platform for managing and orchestrating your AI Agents, simplifying deployment and maintenance.
• Enterprise Data Connectivity: Seamlessly connect your AI Agents with your enterprise data sources, enabling them to access the information they need to make informed decisions.
• Custom AI Agent Development: Build custom AI Agents tailored to your specific business needs, leveraging your LLM model and Multi-Agent Systems.

Conclusion

The Hyperliquid MCP Server v9, available on the UBOS Asset Marketplace, represents a significant step forward in the integration of AI into decentralized finance. By providing AI agents with seamless access to the Hyperliquid exchange, this server empowers them to execute sophisticated trading strategies, manage positions efficiently, and optimize trading performance. Whether you are a seasoned trader or just getting started with AI-driven trading, the Hyperliquid MCP Server v9 is an essential tool for unlocking the full potential of the Hyperliquid exchange.