Hyperliquid API Key Security: Agent Wallets, Rotation and VPS Rules (2026)

1. Master wallet vs API wallet

Everything on HyperCore is a signed transaction. The account is an EVM address, and the private key that owns that address — the master key — can do anything, including withdrawing to Arbitrum. To let software trade without exposing that key, the master signs an approveAgent action that authorises a second EVM key, the API wallet (the docs use "agent wallet" interchangeably), to sign trading actions on its behalf. The app does this for you at app.hyperliquid.xyz/API; the Python SDK does it with exchange.approve_agent().

	Master wallet	API wallet (agent)
What it is	The EVM private key that owns the account	A separate EVM key the master approves to sign for it
Created at	Your wallet (Rabby, MetaMask, hardware…)	app.hyperliquid.xyz/API or the approveAgent action
Can trade	Yes	Yes — orders, cancels, leverage, TWAP
Can withdraw / send funds out	Yes	No
Can approve other agents	Yes	No
Expiry	Never	Up to 180 days (custom valid_until allowed)
How many	1	1 unnamed + 3 named per master, +2 per sub-account
Belongs on a VPS	Never	Yes, and only there

Two details trip people up. First, the agent key signs, but the account is still the master: when you query state or configure the SDK, account_address is the master address and secret_key is the agent's key. Querying the agent's own address returns an empty account. Second, a master can approve agents for its sub-accounts too; sub-accounts and vaults have no keys of their own, so an agent (or the master) signs with vaultAddress set to the sub-account's address.

The safe order of operations for a new bot account:

1. Create the master account from a self-custody wallet (ideally a hardware wallet), with a referral code if you want one: it can only be added before the account passes $10,000 of volume.
2. Fund it with working capital only, from the master wallet.
3. Generate the agent at app.hyperliquid.xyz/API on the machine that holds the master key, give it a name and a short validity (30–90 days; the cap is 180 days), and sign approveAgent.
4. Move only the agent's private key to the bot host, into a secrets manager or a root-only environment file. The master key never leaves the hardware wallet.

2. Read-only data needs no key: balance, positions, fills, trade history

You want	Info request ("type")
Perp account balance, margin, positions, withdrawable	clearinghouseState
Spot token balances	spotClearinghouseState
Open orders	openOrders / frontendOpenOrders
Your fills (user trades)	userFills: latest 2,000
Trade history over a date range	userFillsByTime: pages back through the 10,000 most recent fills
Order history, account value / PnL, fee tier	historicalOrders, portfolio, userFees

Two rules matter. Pass the master or sub-account address; the agent wallet's own address returns an empty account, a common cause of "my balance API returns zero" (Hyperliquid's docs warn about exactly this). And remember that the same reads work for anyone who knows your address, so these endpoints are public, not private. Request bodies and response fields for each request are in our Hyperliquid API docs guide. For anything older than the fill window (candles, trade tapes, S3 archives), see Hyperliquid historical data: trades and fills; to export your own trades to a spreadsheet, see the Hyperliquid trade history CSV export guide.

Choosing an API provider for a bot? The public endpoint is free; its limit is 1,200 REST weight per minute per IP. Paid node and data providers add capacity, latency and history, and none of them needs your master key: a "provider" or bot service that asks for your seed phrase or master private key is a scam. The pricing section of the Hyperliquid API guide compares the options, and Perp DEX APIs and trading bots compares Hyperliquid's API with other venues.

3. "Permissions": what an agent can and cannot sign

Old guides describe permission checkboxes, withdrawal toggles and IP whitelists for Hyperliquid API keys. None of that exists. The boundary is fixed by the protocol: actions come in two signing schemes, and agents can only produce the first kind. Classifying the exchange endpoint's documented actions:

Action	Signable by an agent?
order, cancel, cancelByCloid, modify, batchModify	Yes
updateLeverage, topUpIsolatedOnlyMargin	Yes
twapOrder, twapCancel, scheduleCancel	Yes
agentSendAsset (perp ↔ spot inside the same address)	Yes
subAccountTransfer, vaultTransfer (funds stay under the master)	Yes
reserveRequestWeight (spends 0.0005 USDC per action from perp balance)	Yes
withdraw3 (bridge withdrawal)	No — user-signed
usdSend, spotSend, sendAsset to another address	No — user-signed
approveAgent, approveBuilderFee	No — user-signed
cDeposit / cWithdraw / tokenDelegate (staking)	No — user-signed

The official SDK's agent example states it plainly: "The agent does not have permission to transfer or withdraw funds." There is no read-only agent either, because reading needs no key at all — the info endpoint is public. And there is no way to restrict an agent to one coin, one side or one size; those limits must be enforced in your bot's code.

4. What an attacker can do with a stolen agent key

Because withdrawals are user-signed, a leaked agent key cannot move your money to the attacker's address. That is the good news, and it is where most guides stop. The bad news is that an agent controls the full trading surface of the account:

• Burn the balance through trading. Open a max-leverage position and let it liquidate — the 40x BTC maintenance margin is 1.25%, so it does not take a big move. Or, more precisely, trade the victim account against the attacker's own account in an illiquid market: buy high from themselves, sell low to themselves. The loss lands in your account as bad fills and the profit in theirs. This is the standard extraction technique for trading-only keys on any exchange.
• Reach your sub-accounts. If the agent was approved for sub-accounts, the same applies there. subAccountTransfer is an ordinary L1 action, so an agent can shuffle USDC between master and sub-accounts to concentrate capital where it wants to trade.
• Lock capital. vaultTransfer is agent-signable, so funds can be deposited into a vault (withdrawals from user vaults are subject to the vault's lock-up rules — funds stay yours, but not liquid).
• Waste small amounts via reserveRequestWeight at 0.0005 USDC per reserved action, and exhaust your address-based rate limit so your own bot is throttled to one action every 10 seconds.

What they cannot do: withdraw, send USDC or spot tokens to any other address, bridge to HyperEVM, stake or unstake, approve new agents, or change your referral and builder-fee approvals. As soon as you revoke the agent, the exposure ends; the master key remains the only path to withdrawal.

5. Nonces: why replay protection depends on you

Hyperliquid's replay protection is unusual, and the docs contain a security warning that most bot builders skip. Every signed action carries a millisecond-timestamp nonce. The chain stores the 100 highest nonces per signer; a new action must be higher than the smallest stored nonce, never used before, and inside (T − 2 days, T + 1 day) of block time. That set is tracked per signing key — an agent that signs for the master and two sub-accounts shares one set across all three.

The catch: when an agent is deregistered, expires, or its master account runs out of funds, its nonce state may be pruned. If you later re-approve the same agent address, previously signed actions could be replayed against you. The docs' wording is "strongly suggested to not reuse their addresses". So: every rotation uses a freshly generated key, and if you must invalidate an in-flight nonce, send the noop action rather than re-approving anything. Set expiresAfter on actions so a captured request cannot be submitted minutes later — noting that actions rejected as expired cost 5× the usual address rate limit.

6. Key rotation

The protocol enforces a ceiling: an agent's approval can be valid for at most 180 days, and you can set a shorter window by appending valid_until and a millisecond timestamp to the agent name at approval time. A sensible policy for a bot that runs unattended:

1. Generate a new key on the machine that holds the master (hardware wallet or offline laptop) — never on the VPS.
2. Approve it with the same agent name as the key it replaces. The docs specify that approving a named agent with a matching name deregisters the old one, so the swap is atomic: at no point are two bots authorised under that name.
3. Deploy the new key to the VPS's secret store, restart the bot, confirm a test order rests and cancels.
4. Destroy the old key material. Do not archive it "just in case".

Rotate on a 30–90-day schedule, and immediately when: a person with access leaves, a laptop or server is lost or re-imaged, a key shows up in logs, crash dumps or a git history, or you see fills you did not place. Note the slot limits while planning: 1 unnamed + 3 named agents per master account, +2 named per sub-account. If every strategy gets its own agent, you will run into those limits before you run out of strategies — sub-accounts are how you scale.

7. IP and VPS hygiene (the allowlist you have to build yourself)

Because Hyperliquid has no IP allowlist, the network perimeter is entirely yours. (An "IP not allowed" block in the app is a different thing: it comes from the Terms of Use, not from your API key, and our Hyperliquid restricted countries guide covers it.) The host that runs the bot is the only place the agent key exists, so harden it as if it were a wallet:

• Dedicated VPS per bot or per strategy group. No shared boxes with other tools, no desktop use.
• SSH keys only, password login disabled, root login disabled, and a non-root user runs the bot. Consider changing the SSH port and fail2ban, but keys-only is the control that matters.
• Firewall: inbound closed except SSH from your IP; outbound limited to HTTPS/WSS to api.hyperliquid.xyz (and the testnet host while testing). A compromised bot that cannot reach a command server is much less useful to an attacker.
• Key storage: environment variable injected at start, a secrets manager, or a root-only file with 600 permissions. Never in the repository, never in a Docker image layer, never in config.json committed to git. Add the config file to .gitignore before the first commit.
• Logs: make sure the signing layer never logs the key or the full signed payload. Crash reporters and error trackers are a classic leak path.
• Pinned dependencies. The SDK signs with your key; a compromised transitive dependency has the same access. Pin versions, review lockfile diffs on update, and do not paste signing snippets from random repos — the docs themselves warn that hand-rolled signatures fail silently.
• Automatic updates and reboots for the OS, with the bot under a supervisor so it comes back — and with scheduleCancel armed so the exchange cancels your orders while it is down.

8. Account architecture that limits the blast radius

Since an agent can trade everything in the account it is approved for, the amount at risk is whatever sits in that account. Structure accordingly:

• Master wallet on a hardware wallet. It signs approvals, deposits and withdrawals — nothing else, and never from the VPS.
• Working capital only on Hyperliquid. Keep reserves in your own wallet on Arbitrum or Base and top up as needed; deposits are free apart from source-chain gas, and withdrawals cost 0.2 USDC plus a tiny HyperEVM gas fee in HYPE.
• One sub-account per strategy, one agent per sub-account. Up to 10 sub-accounts unlock after $100,000 of volume, growing to a maximum of 50. Sub-accounts share the master's fee tier but do not receive the referral discount, so keep discretionary trading on the master if you joined with a referral code.
• Hard limits in the bot: max position, max leverage, symbol allowlist, daily loss stop, max orders per minute. Authentication proves who is signing; it says nothing about whether the strategy is sane.
• Independent monitoring: a read-only watcher (no key needed) on a different host that subscribes to userFills and orderUpdates for the master address and alerts on fills the bot did not log. This is your "API usage log" — Hyperliquid does not provide one.

For a trading desk or a company account, the same layering extends to multi-sig approval of the master, portfolio margin and exported records; see institutional crypto trading on a DEX.

9. Incident response in five steps

1. Revoke: from the master wallet, approve a new agent under the same name (or remove the agent in the API page). This deregisters the compromised key instantly.
2. Flatten: cancel all open orders and close positions the attacker opened, from the web app with the master wallet.
3. Withdraw what you do not need for the next session. Withdrawals are master-only, so the attacker cannot race you.
4. Snapshot evidence: pull userFills and historicalOrders for the window, save the VPS logs, then rebuild the host from a clean image. Do not keep trading from a box you suspect.
5. Rotate everything else that host could see: SSH keys, secrets-manager tokens, exchange keys for other venues.

If you see withdrawals or transfers you did not make, the leak is not the agent: only the master key can sign those. Hyperliquid's own support page for hacked accounts says to treat that address as permanently unsafe ("burned"), create a new wallet, move whatever is left there (including HyperEVM assets), revoke token approvals and find out how the key was exposed before you use the new one.

10. How this compares with CEX API keys

Control	Typical CEX API key	Hyperliquid API wallet
Withdrawal permission	Optional toggle	Never possible
Read-only key	Yes	Not needed — reads are public and keyless
IP allowlist	Yes	No — enforce on your VPS
Expiry	Often none	Max 180 days, custom shorter
Scope (symbols, sizes)	Rarely	No — enforce in code
Revocation	Delete key	Approve replacement / remove agent (instant)
Replay protection	Timestamp + recvWindow	Per-signer nonce set; never reuse agent addresses

The net effect: Hyperliquid's model is safer against theft (no withdrawal path at all) and less configurable against misuse (no scoping, no allowlist). Build for the second half yourself, and pair it with the operational rules in the Hyperliquid API guide.

11. Has Hyperliquid been audited?

Partly, and the audited part is not the exchange engine. This is everything Hyperliquid's official Audits and Bug bounty program pages list, read on October 15, 2026:

Component	Security review	Date
Legacy USDC bridge (Bridge2.sol on Arbitrum)	Audited by Zellic: no critical issues, one high and one medium finding, the rest informational	July 10–12, 2023
Bridge changes after that audit	Zellic patch review: no vulnerabilities found	November 23–24, 2023
USDC via CCTP (Circle's contracts)	Hyperliquid's page says "audited independently" and links Circle's contract repository	No report listed
HyperCore L1 (order book, clearinghouse, consensus), HyperEVM, API servers	No audit listed	Not published
Bug bounty (nodes and API servers on mainnet)	Examples ("subject to change"): critical under 1,000,000 USDC, high under 50,000 USDC, medium under 10,000 USDC; reports by email, KYC required	Live on October 15, 2026

Two things follow. First, the legacy bridge is now deprecated: Hyperliquid's USDC docs name CCTP as the preferred route, so the one audited Hyperliquid contract is no longer the main way money moves in and out. Second, both Zellic reports list key custody as out of scope, as every protocol audit does. No audit protects an API wallet you leaked or a master key you typed into a phishing site. Hyperliquid's support guide puts it plainly: only someone with your private key or seed phrase can sign for your address. That is why the rest of this page is about keys.

FAQ

Disclosure: HOLYGRAIL is our referral code; we earn a share of referred accounts' fees. Agent-wallet behaviour, limits and action classifications are taken from Hyperliquid's official API documentation and SDK and re-checked on the date above. This is operational guidance, not a guarantee against loss.