Designing API Wallets for Hyperliquid Trading Systems
API wallets isolate automated signing from the master account, letting a trading system operate without storing the account's highest-authority private key.
A Hyperliquid API wallet, also called an agent wallet in the documentation, is an approved signer that can act for a master account or its subaccounts. The design goal is blast-radius reduction: a bot gets the signing capability it needs without receiving the master key used to control the account and approve new agents.
Master key versus trading key
The master key should be used sparingly for account administration and signer approval. The API wallet can live in the trading infrastructure and sign supported exchange actions.
If the bot host is compromised, the attacker gains the API wallet's practical trading authority, but rotating that signer is preferable to rotating or exposing the master wallet.
One signer per trust boundary
Separate production and testnet. Separate independent strategies when operationally useful. For institutional systems, separate teams or services whose compromise should not automatically affect one another.
This also simplifies nonce coordination because each signer has an independent nonce stream.
Query with the account address
A common documented mistake is querying account state using the API-wallet address. API wallets sign; they do not become the economic account. Data requests should use the master or subaccount address whose positions you want.
Confusing signer identity with account identity can make a system appear to have zero positions immediately before it places a dangerous order.
Lifecycle
Inventory every approved wallet, label its owner and purpose, monitor last use, and deregister unused signers. Never reuse a deregistered private key because of nonce-pruning and replay considerations.
Store secrets in a dedicated secret manager or HSM-backed system where practical, not source code, environment files copied between machines, or browser local storage.
Controls above the protocol
An approved API wallet can still make economically destructive trades. Add application-level notional caps, symbol allowlists, daily loss limits, kill switches, and independent monitoring.
Key separation reduces authority risk. It does not replace trading risk management.