What is an agent wallet? Hyperliquid's API wallets explained

CoTrading editorial team 2026-09-23

Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs.

An agent wallet — Hyperliquid calls it an API wallet — is a separate key pair that a master account approves, through a signed approveAgent action, to sign actions on the master’s behalf, so that automation can trade the account without ever holding the master’s private key.

This page is for developers and anyone connecting a bot or AI assistant to Hyperliquid. It covers what the approval contains, how an agent’s signature is attributed to an account, why agents compete for slots and nonces, and how the model differs from an exchange API key. The step-by-step setup is in Hyperliquid API setup.

Why this matters now

Bots and AI assistants with trading tools need standing authority to place orders. On a centralised exchange that authority is an API key: a key and secret issued by the venue, with permission flags and often an IP allowlist.

Hyperliquid has no API key. Authority is a signing delegation: the account says “signatures from this other address count as mine”. That moves the security question from what flags does this key carry to what can a signature from this address authorise, for how long, and what else shares its slot. Advice written for API keys — “untick withdrawals”, “whitelist your IP” — does not translate one-to-one, which is exactly why read-only vs trade permission treats Hyperliquid as its counter-example.

How it actually works

A fresh key pair is generated. Its public address becomes the agent address. The agent holds no funds and owns nothing; it exists to sign.
The master approves it. Approval is itself a signed action, approveAgent, with the fields agentAddress, an optional agentName, and a nonce. It uses the user-signed scheme — EIP-712 typed data with a hyperliquidChain field set to mainnet or testnet — so an approval belongs to one environment.
An optional expiry is attached. Appending valid_until {timestamp} to the name sets a custom expiration, up to a maximum the exchange endpoint page documents under “Approve an API wallet”.
The agent signs trading actions. Orders, cancels and leverage changes use the L1 scheme. In the official Python SDK, what gets signed is a “phantom agent” whose connectionId is a hash of the msgpack-encoded action, the nonce, an optional vault address and an optional expiresAfter. The master account’s address is not in the signed payload.
The exchange attributes the signature. It recovers the signer’s address from the signature and resolves it against registered agents — the SDK’s helper is literally named recover_agent_or_user_from_l1_action. If the recovered address is not a registered agent or a user, the request fails; that is the User or API Wallet does not exist error.
Sub-accounts and vaults ride on the same key. They have no private keys of their own. To act for one, the master or its agent signs and sets vaultAddress to the sub-account or vault. The docs: “A master account can approve API wallets to sign on behalf of the master account or any of the sub-accounts.”

Slots, and the silent replacement

An account has one unnamed slot and a small, documented number of named slots, with additional named slots per sub-account; the current counts are on the exchange endpoint page.

The deregistration rules are what make this matter:

Approving a new unnamed agent deregisters the existing unnamed one.
Sending approveAgent with an existing name deregisters the agent that held that name.

If two tools each approve an unnamed agent, the second silently evicts the first. From the first tool’s side, the next signed request simply fails. One named agent per tool avoids the collision.

An agent — and its nonce state — can also be pruned when it expires or when the account that registered it no longer has funds.

Nonces belong to the signer

Every /exchange request carries a nonce, and “nonces are tracked per signer”: the account’s address if it signs with its own key, the agent’s address if an agent signs. Hyperliquid keeps a set of the highest recent nonces per signer. A new nonce must be larger than the smallest in that set and never used before, and must fall within a validity window around the block time. The set size and window are on the nonces and API wallets page.

Per the docs, sub-accounts signed by the same agent share one nonce set. Two processes sharing an agent can collide on nonces, so the recommended pattern is one API wallet per trading process, with an atomic counter per batch that can be fast-forwarded to current unix milliseconds.

This is a different job from a centralised exchange’s timestamp and recvWindow. There the timestamp is a freshness check; here the nonce is a replay guard. Freshness is the optional expiresAfter field, which user-signed actions do not support, and an action cancelled for a stale expiresAfter consumes five times the usual address-based rate limit.

Agent wallet vs API key

	Centralised exchange API key	Hyperliquid agent wallet
What it is	Key and secret issued by the exchange	Key pair you generate, approved by the master
How scope is set	Permission flags on the key	`approveAgent` carries an address, optional name and nonce; we did not find a scope field
Network restriction	Commonly an IP allowlist	We did not find an equivalent in the approval
Lifetime	Venue policy	Optional `valid_until` expiry; pruned on expiry, deregistration or an unfunded account
What you query	The key identifies the account	The master or sub-account address, never the agent’s
Replay protection	Timestamp window	Per-signer nonce set

Two other things are easy to confuse with an agent. A sub-account is the inverse: an account with no key, where an agent is a key with no account. And the fees page describes linking a staking user to a trading user for fee discounts, warning that the staking user can then unilaterally transfer all of the trading user’s funds and that the link is permanent. That is a far broader delegation than an agent.

Can an agent wallet withdraw?

Hyperliquid’s docs do not say whether an API wallet can sign withdrawals. The official SDK handles withdrawals and transfers with a different signing scheme from trading, and third-party integrations (e.g. NautilusTrader) state that these require the master key. Verify against your own setup before treating it as a security boundary.

Two details matter. First, vaultTransfer is not in the same bucket: the official SDK signs it as an L1 action, like an order, and we did not find a statement either way on whether an agent may sign it. Second, the fact that the master’s address is absent from a signed withdrawal proves nothing on its own, because it is absent from signed orders too — and an order signed by an agent still acts for the master.

Where the boundary should sit

Treat an agent key as full trading authority over every account it can sign for. An agent approved by the master can sign for any sub-account, so moving a strategy’s capital into a sub-account does not, by itself, limit what that agent can trade.
One named agent per tool or process. It prevents silent eviction and gives each process its own nonce set.
Set valid_until explicitly and record the date somewhere you will see it.
Keep the master key off automation hosts. The process needs the agent key and the master address, nothing more.
Retire addresses, never reuse them. The docs warn that once nonce state is pruned, previously signed actions can be replayed.
Test fund-moving actions on testnet with your own agent before your security model depends on the answer.

For AI assistants, Hyperliquid MCP setup and the exchange API key security checklist apply these rules.

FAQ

What is an agent wallet on Hyperliquid?

An agent wallet, which Hyperliquid’s docs call an API wallet, is a separate key pair that a master account approves with a signed approveAgent action. It can then sign trading actions for the master or its sub-accounts. It holds no funds, and account queries must use the master’s address rather than the agent’s.

How many agent wallets can a Hyperliquid account have?

An account has one unnamed slot and a small number of named slots, with extra named slots per sub-account. The current counts, and the maximum custom expiry, are on the exchange endpoint page under “Approve an API wallet”. Approving a new unnamed agent replaces the existing unnamed one, so give each tool its own named agent.

Can a Hyperliquid agent wallet withdraw funds?

Hyperliquid’s docs do not say whether an API wallet can sign withdrawals. The official SDK handles withdrawals and transfers with a different signing scheme from trading, and third-party integrations such as NautilusTrader state that these require the master key. Verify against your own setup before treating it as a security boundary.

Do Hyperliquid agent wallets expire?

They can. A custom expiry is set by appending valid_until with a timestamp to the agent’s name, up to a documented maximum, and an expired agent is pruned along with its nonce state. Set the expiry explicitly and record it.