Hyperliquid API Setup
Connecting Your Hyperliquid Account
To trade in LIVE mode, Jungle Rebounder needs access to your Hyperliquid account via API credentials. This guide walks you through the setup process step-by-step.
💡 Note: You don't need API credentials for DRY mode (paper trading). DRY mode uses a virtual balance and doesn't connect to Hyperliquid. Only set up API credentials when you're ready to trade with real funds.
What is Hyperliquid?
Hyperliquid is a decentralized perpetuals exchange where you can trade cryptocurrency futures. Jungle Rebounder uses Hyperliquid's API to execute trades on your behalf when you're in LIVE mode.
Step 1: Get Your API Credentials
🔒 Recommended: Use API Wallets (Agent Wallets) for Better Security
For maximum security, use an API wallet (agent wallet) instead of your main wallet. API wallets can only sign transactions and cannot withdraw funds, providing better security isolation.
⚠️ Important: Master Account Address Required
If you use an API wallet, you must provide your master account address. This is required because:
- Base Size Calculations: Order sizes are calculated based on your account equity. Without the master account, the system can't determine your actual balance
- Balance Queries: Your portfolio balance is pulled from the master account to display in the header and configuration
- Risk Management: Max loss limits, exposure limits, and daily loss limits are all calculated as percentages of your account balance
- Position Tracking: Open positions and orders are associated with the master account, not the API wallet
API wallets don't hold funds or positions - they're only for signing transactions. The master account is where your actual balance and trading activity exists.
Option A: Using API Wallet (Recommended for Security)
- Visit Hyperliquid Exchange
- Connect your main wallet and sign in to your account
- Navigate to API/Agent settings
- Create a new API wallet (agent wallet) - this will generate a new wallet address and private key
- Copy both:
- API Wallet Address: The agent wallet address (for signing transactions)
- API Wallet Private Key: The agent wallet's private key
- Master Account Address: Your main wallet address (for balance queries)
Option B: Using Main Wallet
- Visit Hyperliquid Exchange
- Connect your wallet and sign in to your account
- Copy your wallet address and private key
- Note: Using your main wallet is less secure. API wallets are recommended.
⚠️ Security Warning: Never share your private key with anyone. Jungle Rebounder encrypts and securely stores your credentials. API wallets (agent wallets) are recommended as they can only sign transactions and cannot withdraw funds, providing better security isolation.
Step 2: Connect to Jungle Rebounder
You can connect your API credentials through either interface:
🌐 Web Dashboard
- Navigate to Settings → API Credentials
- Enter your Hyperliquid API key (wallet address or API wallet address)
- Enter your Hyperliquid API secret (private key)
- If using API wallet: Enter your master account address (required field) - this is needed for balance queries, base size calculations, and risk management
- Click "Save" - credentials are encrypted and stored securely
- The system will automatically retrieve your account balance from the master account
- Go to Configuration page and switch to LIVE mode
- Your portfolio balance will be displayed in the header and used for base size calculations
📱 Telegram Bot
- Send
/connect_apicommand to the bot - Follow the prompts to enter your API key and secret
- Credentials are saved and encrypted automatically
- Use
/liveto switch to LIVE mode
What You Need
- API Key: Your Hyperliquid wallet address (or API wallet address for better security)
- API Secret: Your wallet private key (or API wallet private key)
- Master Account Address: (Required if using API wallet) Your main wallet address that holds your funds. This is used for:
- Balance queries (to display portfolio value)
- Base size calculations (determines order sizes based on your equity)
- Risk management (max loss, exposure limits based on account balance)
- Position tracking (viewing open positions and orders)
💡 Automatic Balance Retrieval: When you connect your API credentials, Jungle Rebounder automatically retrieves your account balance from the master account (or your main wallet if not using an API wallet). This balance is:
- Displayed in the header showing your portfolio value
- Used to calculate optimal base order sizes based on your actual portfolio equity
- Used for risk management calculations (max loss, exposure limits as percentages of balance)
- Updated automatically as your balance changes
Why Master Account is Required: API wallets don't hold funds or positions - they're only for signing transactions. To calculate base sizes, manage risk, and track positions, we need to query your master account where your actual balance and trading activity exists.
Security Best Practices
- Use API Wallets (Agent Wallets): For maximum security, use API wallets instead of your main wallet. API wallets can only sign transactions and cannot withdraw funds.
- Use Trading-Only Keys: Only grant trading permissions, never withdrawal permissions
- Rotate Keys Regularly: Generate new API keys periodically for better security
- Monitor Activity: Check your Hyperliquid account regularly for unexpected trades
- Test First: Always test in DRY mode before going LIVE
- Start Small: Begin with small position sizes when first using LIVE mode
- Keep Secrets Secure: Never share your API secret with anyone
How Jungle Rebounder Uses Your API
Jungle Rebounder uses your Hyperliquid API credentials to:
- Place market and limit orders for sequences
- Check account balance and positions
- Monitor open positions and PnL in real-time
- Execute grid orders for averaging down
- Close positions when profit targets or loss limits are reached
🔒 Security: Jungle Rebounder never has access to withdraw funds. Your API credentials only grant trading permissions, ensuring your funds remain secure. Even if someone gained access to your Jungle Rebounder account, they could only trade (not withdraw).
Troubleshooting
Cannot connect to Hyperliquid:
- Verify API credentials are correct (check for typos or extra spaces)
- Ensure API keys have trading permissions enabled
- Check that your wallet has sufficient balance
- Verify your IP isn't blocked (if Hyperliquid requires IP whitelisting)
- Try regenerating API keys if connection issues persist
Orders not executing:
- Check account balance and margin requirements
- Verify API keys have trading permissions
- Ensure you're in LIVE mode (not DRY mode)
- Check Hyperliquid exchange status
- Review risk limits - you may have hit daily loss limit or exposure limits
Additional Resources
- Hyperliquid Official Documentation - Complete API reference
- Hyperliquid Exchange - Access the exchange
Need more help? Check the Troubleshooting Guide or Contact Support.