API wallets and agents

An API wallet, also called an agent, limits what a stolen trading key can do. Your bot’s key sits on a server, and if it were your account key a breach would drain the account. An agent is a second key your cold master approves: it signs orders and cancels but can’t move money to another address.

Say your account holds 50,000 USDC and the bot’s server is breached. The thief can lose that 50,000 through bad trades, but can’t withdraw it or send it to another address.

What an agent can sign, and what only the master can

The master signs approveAgent naming the agent’s address and an optional name. The agent then signs L1 actions for the master and its sub-accounts, only on the network hyperliquidChain binds: a testnet approval does nothing on mainnet.

Who can sign	Actions
An agent (L1 actions)	orders, cancels, modifies, scheduleCancel, vault transfers, borrowLend, agentSetAbstraction, HIP-3 and HIP-4 deployer actions such as settlements, cDeposit2 (a deposit into staking), and agentSendAsset, between the account’s own balances only (destination must equal source)
The master key only (user-signed)	withdrawals (withdraw3), staking withdrawals (cWithdraw), sends to another address (usdSend, spotSend, sendAsset), approving another agent, approving a builder fee
Never an agent, even an approved one	activateOutcomeDeployer

Measured on testnet, an agent-signed cWithdraw was refused with an error naming the agent’s own address, and the master’s stake was unchanged.

An agent is a signer, not an account: queries on its address return empty (nonces and agents).

Slots, expiry and removal

Slots. One unnamed slot, several named ones; approving into an occupied slot or name replaces the holder. A valid_until <timestamp in milliseconds> suffix on the name sets an expiry, at most 180 days ahead.

Removal. There is no revoke action. Per the docs an agent and its nonce state may be pruned when it is replaced, when it expires, or when the registering account has no funds. In each case the re-approval danger below applies.

The numbers

Item	Value	Source
Unnamed agents per account	1	exchange endpoint docs
Named agents per account	up to 3, plus 2 per sub-account	exchange endpoint docs
API wallets per account	3 per master, plus 2 per sub-account	sub-accounts docs
Observed, 2026-11-03	14 named, all unexpired, on an account with 1 sub-account	live extraAgents, subAccounts
Longest expiry	180 days	exchange endpoint docs
Agent name length	1 to 16 characters	SDK constants
Nonces kept per signer	the 100 highest	nonce docs
Nonce window	block time minus 2 days to block time plus 1 day	nonce docs

The official docs differ

On 2026-11-03 one mainnet account with 1 sub-account held 14 named API wallets, all unexpired, where the docs allow 5 named (3, plus 2 for its sub-account). It had about 9.3M USDC of cumulative volume; whether the real allowance grows with volume is undocumented. Read extraAgents on your own account rather than relying on either number.

Keeping a trading key safe

• Retire a leaked key by approving a fresh address into its slot or name. Until then it trades without limit.
• Set a valid_until expiry so a forgotten agent stops on its own.
• Run one agent per process. Nonces are per signer, so processes sharing one collide. The docs recommend one API wallet per trading process and per sub-account.

Never re-approve an old agent address

A replaced agent’s used-nonce record may be pruned, so re-approving its address lets actions it signed before be replayed. Generate a new key for every approval.

Approving and inspecting agents from code

The master key signs the approval; a null agentName signs as the empty string and approves the unnamed agent.

{
  "type": "approveAgent",
  "hyperliquidChain": "Mainnet",
  "signatureChainId": "0xa4b1",
  "agentAddress": "0x...",
  "agentName": "mm-1 valid_until 1767225600000",
  "nonce": 1760000000000
}

• Listing: extraAgents returns {name, address, validUntil} entries. On 2026-11-03 accounts with none returned []; one codebase records null, so handle both.
• Identifying: userRole returns {"role": "agent", "data": {"user": "0x..."}}, naming the master.
• From a contract: CoreWriter action 9, (address wallet, string name), approves an API wallet for the contract’s own account; an empty name makes it the main agent. An off-chain keeper can then do what CoreWriter is not proven to carry, such as a borrow.
• CoreWriter acts for the sender: an agent’s key calling CoreWriter acts for the agent’s own address, not its master.
• Multi-sig: the submitting leader can be an authorised user’s API wallet; its nonce is the one checked (multi-sig).
• Builder fees: an app can’t approve its own builder fee through a user’s agent (builder codes).
• Unknown signer: an unapproved or replaced agent, or a malformed signature, fails with User or API Wallet ... does not exist, naming the recovered address (debugging).

For signing and replay protection in depth, see Nonces, expiry and API wallets. For L1 versus user-signed actions, see Signing from first principles.