All builder guides

Hyperliquid bot builder reference

Hyperliquid API Wallets (Agent Wallets)

What a Hyperliquid API wallet can and cannot do, how to create and use one, which address to query, nonce rules and why a wallet stops working.

Last verified: November 17, 2026 Markdown version Example code

An API wallet is a second key that can trade for your Hyperliquid account but cannot withdraw from it. The Hyperliquid docs also call it an agent wallet. Use one for every bot.

What an API wallet can do

  • It can sign trading actions for the main account: place, modify and cancel orders, and change leverage.
  • It can sign for the sub-accounts of the main account.
  • It cannot withdraw funds. If the key leaks, an attacker can trade the account but cannot move the money out of it.

An API wallet holds no funds. It only signs.

Create one

  1. Open app.hyperliquid.xyz/API. For testnet, open app.hyperliquid-testnet.xyz/API.
  2. Enter a name for the wallet and select Generate.
  3. Select Authorize API Wallet and sign with your main wallet.
  4. Copy the private key and store it safely.

Store the key in an environment variable or a .env file. Do not put it in source code or in a repository.

Use it in code

Sign with the API wallet key. Pass the main account address as account_address.

python
from eth_account import Account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

wallet = Account.from_key(API_WALLET_PRIVATE_KEY)
MAIN_ACCOUNT = "0x..."     # the account that approved the API wallet

exchange = Exchange(wallet, constants.MAINNET_API_URL, account_address=MAIN_ACCOUNT)
info = Info(constants.MAINNET_API_URL, skip_ws=True)

positions = info.user_state(MAIN_ACCOUNT)      # correct
# info.user_state(wallet.address)              # wrong: returns an empty account

The most common mistake

To read account data, pass the address of the main account or the sub-account. Do not pass the address of the API wallet. The API wallet has no balance, no positions and no orders, so the result is empty and looks like a bug.

The same rule applies to WebSocket subscriptions for user data.

Check which API wallets are approved

python
info.post("/info", {"type": "extraAgents", "user": MAIN_ACCOUNT})

The response lists the API wallets that the account has approved.

Errors that point to the key

ResponseUsual cause
User or API Wallet 0x... does not exist.The signing key is not an approved API wallet for this account on this network, or the account has never deposited.
Empty positions and ordersThe code reads the API wallet address, not the main account address.

The address in the first error is the address that Hyperliquid recovered from the signature. If it is not your API wallet address, the wrong key signed the request, or the request used the mainnet key on testnet.

When an API wallet stops working

Hyperliquid can remove (prune) an API wallet in three cases:

  • It is replaced. An account has one unnamed API wallet. If you approve a new unnamed wallet, the old one is removed. If you approve a named wallet with a name that is already used, the old wallet with that name is removed.
  • It expires. An approval can have an expiry date.
  • The account has no funds. If the account that approved the wallet is empty, the wallet can be removed.

Do not use an old API wallet address again. After a wallet is removed, Hyperliquid can discard its record of used nonces. An old signed action could then be replayed. Generate a new key each time.

Nonces

Each action has a nonce. Use the current time in milliseconds. The SDK does this for you.

  • Hyperliquid stores the 100 highest nonces for each signer.
  • A new nonce must be larger than the smallest stored nonce, and must not have been used before.
  • A nonce must be in the range from 2 days before to 1 day after the block time.

Nonces are stored for each signer, not for each account. Two processes that share one API wallet key also share one set of nonces, and their actions can collide.

One API wallet for each process

Give each bot process its own API wallet. To trade several sub-accounts at the same time, approve a separate API wallet for each sub-account.

To trade for a sub-account or a vault, pass its address as vault_address:

python
exchange = Exchange(wallet, constants.MAINNET_API_URL, vault_address=SUB_ACCOUNT)

What an API wallet cannot sign

Some actions need the main wallet signature. An API wallet cannot sign them.

  • Withdrawals and transfers to other addresses.
  • Approval of a builder fee (approveBuilderFee).
  • Approval of another API wallet.

Sources

  • Nonces and API wallets, Hyperliquid docs
  • Builder codes, Hyperliquid docs
  • The does not exist response and the empty-account result were reproduced on testnet on November 17, 2026.

More builder guides

New to Hyperliquid?

The referral code HIPERWIRE gives a new account 4% off trading fees on its first $25M of volume. It also funds this reference. HIPERWIRE is independent and is not affiliated with Hyperliquid.

Open Hyperliquid with code HIPERWIRE