How to Set Up API Trading or Bots on Hyperliquid

An API key on Hyperliquid isn’t a copy of your main account credentials, it’s a separate “agent wallet” that can trade on your behalf but explicitly cannot withdraw funds, by design.

This guide is part of TradeOnDEX’s Hyperliquid how-to series within Perpetual Futures, written for traders connecting bots or third-party tools rather than for the underlying developer API itself.

Disclosure: TradeOnDEX may earn a commission from links to Hyperliquid on this page, at no extra cost to you. Full details at the end of this article.

What an agent wallet actually is

An agent wallet (also called an API wallet) is a separate keypair your main account authorizes to act on its behalf, scoped specifically to trading actions. It’s built so that even if the agent key is compromised, an attacker can trade or manipulate your positions, but cannot move funds off the platform, withdrawals remain gated to your main wallet.

This means for you, concretely: connecting a bot to Hyperliquid doesn’t require handing over your main wallet’s keys, and a leaked bot credential is a serious problem, but a fundamentally different (and generally smaller) one than a leaked main wallet key.

How to create an agent wallet, step by step

1. Make sure your account is funded, some bot platforms require a deposit to already exist before authorization succeeds.
2. Go to app.hyperliquid.xyz, click your wallet address in the top right, and select API.
3. Enter a name for your API wallet (something identifying which bot or strategy it’s for).
4. Confirm your main account wallet address.
5. Click Generate, then Authorize API Wallet when prompted, this step is signed by your main wallet.
6. Choose a validity period (up to a maximum of 180 days as of this writing).
7. Copy the private key shown on screen immediately and store it in a secure password manager, it is typically shown only once.
8. Enter this key into your bot platform (Hummingbot, WunderTrading, Gunbot, and others commonly support Hyperliquid) alongside your main account address.

Risk: what a compromised agent key actually costs you, and what it doesn’t

A leaked agent key can be used to trade against you, but not to steal your funds directly. An attacker with your agent key could open unwanted positions, cancel your existing orders, or otherwise “grief” your account’s trading activity, genuinely damaging, but structurally different from a stolen main wallet key, which could move funds out entirely.

Using one agent wallet per strategy isn’t just tidy, it limits the blast radius of a single leak. If one bot or integration is compromised, an isolated agent wallet confines the damage to that specific strategy’s activity, rather than exposing every automated system connected to your account.

A validity period that’s too long increases your exposure window unnecessarily. Since keys expire after a maximum of 180 days, treat that ceiling as a maximum, not a default, set a shorter validity period if a given bot or strategy doesn’t need that long, and rotate credentials deliberately rather than letting them run indefinitely.

Pasting a private key into an untrusted tool is the most common real-world failure mode, not a sophisticated hack. Only enter your agent wallet’s key into the specific, verified bot platform you intend to use, never into a “helper” tool, support chat, or anything you haven’t independently verified.

A bot’s strategy risk is separate from, and layered on top of, the API security question. Even a perfectly secured agent wallet doesn’t protect you from a poorly designed or malfunctioning trading strategy, the leverage, liquidation, and margin risks covered throughout this series apply just as much to automated trading as to manual trading.

Agent wallet vs. main wallet: what each can and can’t do

See it for yourself

Start by connecting one bot with a short validity period and a modest allocation, and confirm it behaves as expected before scaling up or adding additional strategies. You can generate an agent wallet at app.hyperliquid.xyz/API.

Frequently asked questions

Can a bot withdraw my funds if its API key is stolen?

No, by design, agent wallets can trade but cannot withdraw; that permission stays with your main wallet only.

How long can an agent wallet stay valid?

Up to a maximum of 180 days as of this writing, after which it expires and needs to be regenerated.

Should I use the same agent wallet for multiple bots?

No, using a separate agent wallet per strategy or bot limits the impact if any single one is compromised or misbehaves.

Does using an agent wallet protect me from a bad trading strategy?

No. It secures the connection and permissions, not the strategy itself, a poorly designed bot can still lose money through normal trading risk.

Affiliate disclosure

TradeOnDEX may earn a commission if you sign up or trade through a link on this page, at no extra cost to you. Hyperliquid’s own affiliate/referral terms are still being confirmed for this site, so links here are direct and untracked for now. This article is educational and does not endorse any specific bot platform or trading strategy. See our disclaimer for the full risk warning.