About this guide: I'm Lawrence, the writer behind supa.is. Between February and May 2026 I've published 150+ articles on supa.is across crypto and brokerage tooling — including 30+ Hyperliquid-specific guides (recent examples: Hyperliquid API Rate Limits, Hyperliquid Python SDK Tutorial, Hyperliquid API Websocket Guide). The most-repeated reader question across that Hyperliquid archive is exactly how to configure API agent wallet permissions safely, which is why I'm publishing this standardized guide instead of answering one-off.
Connecting an automated agent or trading bot to Hyperliquid requires more than just generating an API key; it requires understanding the granular permissions that govern what that key can actually do. Unlike centralized exchanges where API keys are often tied to a single account with broad or narrowly scoped permissions, Hyperliquid operates on-chain. Your API key interacts with your wallet, and the permissions you grant determine whether an agent can only read data, execute trades, or withdraw funds.
Misconfiguring these permissions is the fastest way to lose funds. A compromised API key with withdrawal permissions can drain your account in seconds. Conversely, an agent without the correct trade permissions will fail to execute orders, wasting time and potentially missing market movements.
This guide breaks down the exact steps to set up an API agent wallet on Hyperliquid, explains the different permission levels, and provides the security best practices you need to keep your automated trading safe.
Understanding Hyperliquid API Agent Wallets
Hyperliquid is a DEX built on its own L2, meaning your funds sit in a smart contract. Your API key is just a cryptographic signature authorizing actions on your behalf. When you generate one, you're creating a digital proxy with strict boundaries.
You'll encounter three permission types:
- Read-Only: Views balances, positions, and order books. Cannot trade or move funds.
- Trade-Only: Places, modifies, and cancels orders. Cannot withdraw funds.
- Full Access: Reads, trades, and withdraws.
Step-by-Step: Setting Up Your API Agent Wallet
The process of setting up an API agent wallet on Hyperliquid is straightforward, but it requires careful attention to the permission toggles. Here is how to do it safely.
Step 1: Access the API Settings
Log in to your Hyperliquid account via the official app. Navigate to the settings menu, typically found in the user profile dropdown. Look for the "API" or "Developer" section. If you haven't enabled API access before, you may need to activate it first, which might involve a quick email or 2FA verification.
Step 2: Generate a New API Key
Click on "Create New API Key" or "Add API Agent." You will be prompted to give your API key a descriptive name. Use something clear, like "Trading Bot - BTC/ETH" or "Data Fetcher - Read Only." This helps you identify the purpose of the key later if you need to revoke it.
Step 3: Configure Permissions (The Critical Step)
This is where most mistakes happen. You will see a series of toggles or checkboxes for permissions:
* Enable Reading: Toggle this on if your agent needs to check balances, positions, or market data. Almost all agents need this.
* Enable Trading: Toggle this on if your agent needs to place or cancel orders. * Enable Withdrawals: Leave this OFF unless absolutely necessary. This is the most dangerous permission. If a malicious actor gains access to your API key, they can drain your account if this is enabled.For a standard trading bot, you want Reading and Trading enabled, but Withdrawals disabled. For a purely analytical agent, only enable Reading.
Step 4: Set IP Whitelisting (If Available)
If Hyperliquid offers IP whitelisting for API keys, use it. Restrict the API key to only work from the specific IP address of your server or VPS. This adds a layer of security, ensuring that even if your API key is stolen, it cannot be used from a different location.
Step 5: Save and Secure Your Credentials
Once you've configured the permissions, click "Create" or "Save." Hyperliquid will generate your API key and, in some cases, a secret key or passphrase. Copy these immediately and store them securely. You will likely not be able to view the secret key again. Store them in an environment variable on your server, not in plain text in your code repository.
Read vs. Trade vs. Withdrawal: A Deep Dive
Read-Only Permissions
Safe. The agent queries balances, positions, PnL, and order history. If this key leaks, the attacker can only watch your portfolio—they can't touch it. Use this for dashboard integrations or tracking bots.
Trade-Only Permissions
The standard for algorithmic trading. The agent can place, cancel, and modify orders. If this key leaks, a malicious actor can open large positions against you or front-run your bot. However, they cannot move your USDC or HYPE out of the protocol. The damage is limited to the margin already in your account.
Withdrawal Permissions
The highest risk. If enabled, a compromised key can drain your account entirely. There are very few legitimate use cases for an automated agent to have withdrawal permissions. Even if you're building a DeFi routing bot, handle the withdrawal step through a separate, manually triggered process or a cold wallet. Never give a hot API key withdrawal access.
Common Pitfalls When Setting Up API Agent Wallets
Many users rush through the setup process and end up with agents that don't work as expected, or worse, leave their accounts vulnerable. Here are the most common pitfalls to avoid.
1. Over-Granting Permissions
The most frequent mistake is enabling withdrawal permissions out of habit or because the option is available. Always follow the principle of least privilege. Give your agent only the permissions it absolutely needs to function. If your bot only needs to place trades, do not give it withdrawal access.
Like what you're reading? Try it yourself — this link supports ChartedTrader at no cost to you.
Sign up on Hyperliquid →2. Ignoring IP Whitelisting
If Hyperliquid supports IP whitelisting, failing to use it is a significant security gap. An API key stolen from a data breach or a phishing attack can be used from anywhere in the world. By restricting the key to your server's IP address, you neutralize most remote theft attempts.
3. Storing API Keys in Plain Text
Never hardcode your API keys into your source code. If you push your code to GitHub or any public repository, your keys are immediately compromised. Use environment variables, secret management tools, or encrypted configuration files.
4. Not Rotating API Keys
API keys should not be permanent. If you suspect a key has been exposed, or even as a regular security hygiene practice, rotate your keys. This means creating a new key with the same permissions, updating your agent's configuration, and then revoking the old key on Hyperliquid.
5. Confusing Agent Wallets with Sub-Accounts
On some centralized exchanges, sub-accounts are used to isolate risk. Hyperliquid's architecture is different. Your API agent operates on your main wallet. If you are running multiple bots with different risk profiles, consider using different API keys with different trade permissions, but be aware that they all draw from the same margin pool unless you are using isolated margin modes for specific positions.
Securing Your Hyperliquid API Agent
Here are some best practices to keep your API agent wallet secure.
Use a Dedicated Server
Run your trading bot or agent on a dedicated VPS or server. Avoid running it on your personal computer, which is more susceptible to malware and keyloggers. A clean, isolated server environment reduces the attack surface.
Monitor Your Account Activity
Regularly check your Hyperliquid account for unauthorized trades or withdrawal attempts. Set up alerts if possible. If you see a trade you didn't authorize, revoke the API key immediately and generate a new one.
Keep Your Software Updated
Ensure that the software running your agent is up to date. Vulnerabilities in outdated libraries or frameworks can be exploited to steal your API keys or manipulate your bot's behavior.
Understand Portfolio Margin Implications
If you are using Hyperliquid's portfolio margin feature, be aware that your agent's trades will impact your overall margin calculation. A poorly configured bot could open positions that, while not directly withdrawing funds, could lead to liquidation if the margin requirements are not met. The recent update to portfolio margin allows users with account values under $25M to use BTC and HYPE as collateral, which changes how margin is calculated (Hyperliquid Portfolio Margin Beta Limits Increased). Ensure your agent's logic accounts for these margin calculations to prevent unexpected liquidations.
Troubleshooting Common API Agent Issues
Even with the correct permissions, you might encounter issues when your agent tries to connect to Hyperliquid. Here are some common problems and solutions.
"Invalid API Key" Error
This usually means the key was copied incorrectly, or it has been revoked. Double-check the key string for any missing characters or spaces. If you recently rotated your keys, make sure you are using the new one.
"Insufficient Permissions" Error
If your agent tries to place a trade and gets this error, you likely forgot to enable trading permissions. Go back to the API settings and verify that the "Enable Trading" toggle is on. Similarly, if a read-only agent tries to place an order, it will fail with this error.
"IP Address Not Whitelisted" Error
If you have IP whitelisting enabled, this error means the request is coming from an IP address other than the one you specified. This is common if you are testing locally or if your server's IP address has changed. Temporarily disable whitelisting to test, or add the new IP address to your whitelist.
Connection Timeouts
If your agent is timing out when trying to connect to Hyperliquid, it could be a network issue or an API rate limit. Hyperliquid has strict rate limits to prevent abuse. If you are making too many requests too quickly, your key may be temporarily blocked. Review the Hyperliquid API Rate Limits to ensure your agent is compliant.
FAQ
Can I change API permissions after creating the key?
Yes, you can usually modify the permissions of an existing API key through the Hyperliquid settings menu. However, it is often safer and cleaner to revoke the old key and create a new one with the correct permissions, especially if you are removing withdrawal access.What happens if my API key is compromised?
If you suspect your API key has been compromised, revoke it immediately in the Hyperliquid settings. Then, generate a new key with the same permissions and update your agent's configuration. If the compromised key had withdrawal permissions, monitor your account closely for any unauthorized withdrawals.Does Hyperliquid support IP whitelisting for API keys?
Hyperliquid's API infrastructure is evolving. While some versions of the API support IP whitelisting, it is not always available for all key types. Always check the current settings when creating a key. If it's not available, rely on strong key management and regular rotation.How do I know if my agent is using read-only or trade permissions?
You can test this by having your agent attempt to place a small, non-risky order. If it succeeds, it has trade permissions. If it fails with a permissions error, it likely only has read-only access. Alternatively, check the API settings in your Hyperliquid account to see the toggles for the specific key.Is it safe to use an API agent with trade permissions?
Yes, as long as withdrawal permissions are disabled. Trade-only permissions mean the agent can only execute trades within your existing margin. It cannot move funds out of the protocol. The primary risk is that a compromised key could place unwanted trades, but it cannot drain your account.Risk Warning
Risk Warning: Crypto trading involves substantial risk of loss. Never invest more than you can afford to lose. This is not financial advice. API trading can lead to rapid losses if not configured correctly. Always test your agents in a low-risk environment before deploying them with significant capital.
Conclusion
Setting up an API agent wallet on Hyperliquid is a powerful way to automate your trading and data collection. However, the decentralized nature of the platform means that security is entirely in your hands. By carefully configuring permissions, using IP whitelisting, and following best practices for key management, you can safely leverage Hyperliquid's API without exposing your funds to unnecessary risk. Remember, the principle of least privilege is your best defense: give your agent only what it needs, and nothing more.
Continue with Hyperliquid
Browse the Hyperliquid guide hub for the complete user journey.
Official reference: Hyperliquid documentation.