Hyperliquid API Wallets (Agent Wallets) Explained (2026): Permissions, Setup, Risks and Read-Only Tracking

The short version: a Hyperliquid API wallet (also called an agent wallet) is a separate key that your main wallet authorizes to place and cancel orders for it. It can trade, but it cannot withdraw funds. Bots, trading terminals and Telegram trading tools use agent wallets. Portfolio trackers do not need one at all: your Hyperliquid data is public, so a read-only tool like Hyperfolio only needs your address.

What is an API wallet on Hyperliquid?

Every action on Hyperliquid (orders, cancels, leverage changes) is a message signed by a private key. Signing each one with your hardware or browser wallet is slow, and handing your main key to a bot is dangerous. The agent wallet solves this: you generate a fresh key pair, then your main wallet signs a one-time approveAgent action that says “this address may trade on my behalf”. After that, the bot signs with the agent key while orders still land in your account.

What an agent wallet can and cannot do

Action	Agent wallet	Main wallet
Place, modify, cancel orders	Yes	Yes
Change leverage / margin mode	Yes	Yes
Trade for sub-accounts and vaults you lead	Yes (via vaultAddress)	Yes
Withdraw to an external address	No	Yes
Send USDC or tokens to another user	No	Yes
Approve new agents	No	Yes

So a leaked agent key cannot drain your account directly. It can still lose you money: an attacker could open huge leveraged positions or trade against illiquid books. Treat it as a sensitive secret.

How to create an API wallet

1. Connect your main wallet on app.hyperliquid.xyz and open the API page from the menu.
2. Generate a new API wallet (or paste an address you created yourself), give it a name, and optionally set a validity period.
3. Authorize it with a signature from your main wallet. Copy the private key shown once and store it in your bot's secret store, never in code or chat.
4. In your bot, sign with the agent key but pass your main account address as the account to query and trade. Using the agent address for info requests is the most common bug: it has no balance of its own.

Hyperliquid limits how many named agents an account can have, and approving a new agent with an existing name replaces the old one. Check the current limits in the official docs before building multi-bot setups. For code examples see our Python API guide and trading bots guide.

Nonces: why one agent per bot

Hyperliquid tracks nonces per signer, and each signed action needs a recent, unique nonce (usually a millisecond timestamp). If two processes share one agent key, their nonces collide and orders get rejected at random. Give every bot or process its own agent wallet. Do not reuse an old, deregistered agent address either: generate a new key.

Security checklist

• Create the agent key yourself or in the official app; never paste your main seed into a bot, terminal or “AI trading” site.
• Third-party trading tools that ask you to approve an agent can trade your account. Only approve tools you trust, and revoke ones you stopped using.
• Set an expiry when possible and rotate keys after staff changes or server incidents.
• Run bots in a dedicated sub-account so a bug cannot touch your main book.
• Read our wallet security guide for the full threat model.

How to check which agents are approved

The public info API lists the extra agents attached to an address:

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"extraAgents","user":"0xYOUR_MAIN_ADDRESS"}'

If you see a name or address you do not recognise, remove it from the API page and review recent fills.

Do you need an API wallet to track your portfolio?

No. Balances, positions, fills, funding and PnL on Hyperliquid are public on-chain data readable by address. A tracker that asks for an API key, an agent approval or a signature to “show your PnL” is asking for more power than it needs. Hyperfolio is free and read-only: paste your address (plus sub-accounts and bot accounts), and you get equity, open perps, closed and unrealized PnL, fees and funding, with no keys. More in tracking Hyperliquid without API keys.

Example: monitoring a bot safely

You run a grid bot with an agent wallet in sub-account “bot-eth” with $5,000. The bot signs with the agent key; it cannot withdraw. On your phone, Hyperfolio watches “bot-eth” and your master read-only, so you see each day whether the bot's trading PnL survives fees and funding (real PnL guide) without ever putting a key on your phone.

FAQ

Can a Hyperliquid API wallet withdraw my funds?

No. Agent wallets can trade but cannot withdraw or transfer funds; only the main wallet can.

Is an API wallet the same as a sub-account?

No. A sub-account is a separate account with its own balance. An agent wallet is a signing key with no funds that trades for an account.

Why does my bot show zero balance?

You are probably querying the agent address. Query the main (or sub-account) address instead.

How do I revoke an agent?

Remove it on the API page of the Hyperliquid app, or let it expire if you set a validity period.

Does Hyperfolio need an API wallet?

No. Hyperfolio only reads public data by address and never asks for keys, agent approvals or signatures.

Keep your keys for trading, not tracking: watch every Hyperliquid account you run in Hyperfolio, free and read-only. New to Hyperliquid? Code HYPERFOLIO gives 4% off fees.