Hyperliquid MCP Server

# ============================================================================ # HYPERLIQUID MCP SERVER - ENVIRONMENT CONFIGURATION EXAMPLE # ============================================================================ # # This file contains all required and optional environment variables for the # Hyperliquid MCP Server. Copy this file to .env and fill in your actual values. # # SECURITY WARNING: NEVER commit your actual .env file to version control! # The .env file contains sensitive credentials that must be kept private. # # ============================================================================ # REQUIRED CONFIGURATION # ============================================================================ # Hyperliquid Account Private Key # # Description: # Your Ethereum-compatible private key for the Hyperliquid account. # This is used to sign all trading transactions and cannot be changed. # # How to get: # 1. Log into your wallet (MetaMask, Hardware Wallet, etc.) # 2. Export your private key (usually in Settings > Export Private Key) # 3. Copy the full 66-character hex string (including 0x prefix) # # Format: 64 hex characters prefixed with "0x" # Example format: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef # Security: Keep this SECRET! Never share or expose this value. # HYPERLIQUID_PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000000 # Hyperliquid Account Address # # Description: # The public wallet address associated with your Hyperliquid account. # This is your account identifier on the blockchain. # # How to get: # 1. Copy your wallet address from your wallet interface # 2. Or derive it from your private key (first 40 hex chars without 0x) # # Format: 42 characters (0x + 40 hex digits) # Example format: 0x0000000000000000000000000000000000000000 # Security: This is public information, but handle carefully. # HYPERLIQUID_ACCOUNT_ADDRESS=0x0000000000000000000000000000000000000000 # ============================================================================ # NETWORK CONFIGURATION # ============================================================================ # Network Selection # # Description: # Specifies whether to connect to mainnet (live trading) or testnet (testing). # Mainnet transactions use real funds and cannot be reversed. # Testnet is for testing and uses testnet funds only. # # Options: # - mainnet (default) - LIVE TRADING, REAL FUNDS # - testnet - TESTING ONLY, TESTNET FUNDS # # Security Note: Start with testnet to verify your setup! # HYPERLIQUID_NETWORK=mainnet # Mainnet API Endpoint # # Description: # REST API URL for Hyperliquid mainnet. # Do not change unless you're using a custom Hyperliquid instance. # # Default: https://api.hyperliquid.xyz # HYPERLIQUID_API_URL=https://api.hyperliquid.xyz # Mainnet WebSocket Endpoint # # Description: # WebSocket URL for real-time data streaming from mainnet. # Used for market data subscriptions and real-time order updates. # # Default: wss://api.hyperliquid.xyz/ws # HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws # ============================================================================ # TESTNET CONFIGURATION (Optional) # ============================================================================ # # Uncomment the following lines to use Hyperliquid testnet instead of mainnet. # Testnet is perfect for: # - Testing your bot strategy before live trading # - Learning the platform # - Verifying configuration without risk # # Instructions: # 1. Get testnet funds from the Hyperliquid testnet faucet # 2. Uncomment the lines below # 3. Change HYPERLIQUID_NETWORK to "testnet" # 4. Restart your server # # HYPERLIQUID_NETWORK=testnet # HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz # HYPERLIQUID_WS_URL=wss://api.hyperliquid-testnet.xyz/ws # ============================================================================ # MCP SERVER CONFIGURATION # ============================================================================ # Logging Level # # Description: # Controls the verbosity of server logging output. # Useful for debugging issues and monitoring server health. # # Options: # - DEBUG - Detailed logging, includes all function calls and parameters # - INFO - Standard logging, shows important events (default) # - WARNING - Only show warnings and errors # - ERROR - Only show critical errors # - CRITICAL - Only show system-level failures # # For production: INFO or WARNING # For development: DEBUG # For troubleshooting: DEBUG # LOG_LEVEL=INFO # ============================================================================ # RATE LIMITING & PERFORMANCE # ============================================================================ # Rate Limit Weight Capacity # # Description: # Maximum API weight (request cost units) allowed per minute. # Hyperliquid uses a weighted rate limiting system where different # endpoints consume different amounts of weight. # # Hyperliquid's limits: # - Standard accounts: 1200 weight per minute # - Higher tier accounts: up to 2400 weight per minute # # Recommendations: # - Start with 1000 to stay within safe limits # - Monitor usage and adjust based on your needs # - Higher values = faster but with risk of hitting limits # # Weight costs (approximate): # - Market data: 1-10 weight per request # - Trading: 20-50 weight per request # RATE_LIMIT_WEIGHT=1200 # ============================================================================ # OPTIONAL TRADING CONFIGURATION # ============================================================================ # Default Slippage Tolerance # # Description: # Maximum acceptable price change (as decimal) when executing market orders. # Protects against sudden price movements between order creation and execution. # # Example values: # - 0.001 = 0.1% slippage (tight, may fail on volatile assets) # - 0.01 = 1% slippage (moderate) # - 0.05 = 5% slippage (loose, for volatile assets) # - 0.1 = 10% slippage (very loose) # # Note: Only applies if using market orders or implicit slippage handling. # HYPERLIQUID_DEFAULT_SLIPPAGE=0.01 # Maximum Retry Attempts # # Description: # Number of times to retry failed API requests before giving up. # Helps handle temporary network issues. # # Values: # - 1 = no retries, fail immediately # - 3 = retry up to 2 more times (default) # - 5 = retry up to 4 more times (for unreliable networks) # # Note: Each retry includes exponential backoff delay. # HYPERLIQUID_MAX_RETRY_ATTEMPTS=3 # Request Timeout Duration # # Description: # Maximum seconds to wait for an API response before timing out. # Prevents the server from hanging on slow or unresponsive API calls. # # Values (in seconds): # - 10 = fast timeout, may fail on slow connections # - 30 = standard timeout (default) # - 60 = slow timeout, waits longer for response # # Note: WebSocket operations use WS_TIMEOUT instead. # HYPERLIQUID_REQUEST_TIMEOUT=30 # ============================================================================ # CONNECTION TIMEOUTS # ============================================================================ # HTTP Request Timeout # # Description: # Timeout for all HTTP/REST API requests in seconds. # # Default: 30 seconds # Range: 5-120 seconds # HTTP_TIMEOUT=30 # WebSocket Connection Timeout # # Description: # Timeout for WebSocket connections and subscriptions in seconds. # Includes timeout for initial connection establishment. # # Default: 60 seconds # Range: 10-300 seconds # # Note: Must be higher than HTTP_TIMEOUT for WebSocket stability. # WS_TIMEOUT=60 # ============================================================================ # DEBUG & DEVELOPMENT # ============================================================================ # Enable Debug Mode # # Description: # Activates detailed debugging output and verbose logging. # Also disables some safety checks for easier troubleshooting. # # Values: # - false = disabled (default, production mode) # - true = enabled (development and debugging) # # WARNING: Do NOT enable in production! # Debug mode may: # - Log sensitive information # - Print API responses with raw data # - Reduce performance slightly # - Disable some safety checks # DEBUG=false # ============================================================================ # QUICK START GUIDE # ============================================================================ # # 1. TESTNET SETUP (Recommended First): # a. Get testnet ETH from Hyperliquid testnet faucet # b. Set HYPERLIQUID_NETWORK=testnet # c. Uncomment TESTNET URLs # d. Test your configuration # # 2. MAINNET SETUP (With Real Funds): # a. Ensure testnet works perfectly first # b. Set HYPERLIQUID_NETWORK=mainnet # c. Use mainnet URLs (already default) # d. Start with small amounts # # 3. TROUBLESHOOTING: # a. Set LOG_LEVEL=DEBUG for detailed logs # b. Check that private key and address match # c. Verify network selection (mainnet vs testnet) # d. Check API endpoint URLs are correct # e. Ensure rate limit weight is appropriate # # 4. SECURITY CHECKLIST: # - Never commit .env to version control # - Use .gitignore to exclude .env # - Rotate keys periodically # - Use hardware wallets for mainnet # - Start with testnet for testing # # ============================================================================ # SUPPORT & DOCUMENTATION # ============================================================================ # # Repository: https://github.com/yourusername/hyperliquid-mcp-server # Hyperliquid Docs: https://hyperliquid.gitbook.io # MCP Protocol: https://modelcontextprotocol.io # # For issues: # 1. Check logs with: tail -f logs/mcp.log # 2. Enable DEBUG mode in .env # 3. Open an issue with your configuration (without exposing keys) # # ============================================================================