# Canonical: https://www.uddalak.xyz/hyperliquid-academy/article/89-designing-api-wallets-for-trading-systems
# Author: Uddalak Das
# Last source: https://www.uddalak.xyz/hyperliquid-academy/article/89-designing-api-wallets-for-trading-systems

---
title: "Designing API Wallets for Hyperliquid Trading Systems"
description: "API wallets isolate automated signing from the master account, letting a trading system operate without storing the account's highest-authority private key."
pillar: "Architecture & Build"
track: "Architecture & Build"
cluster: "Architecture & Build"
level: "Advanced"
primary_icp: ["builder", "institutional decision-maker"]
secondary_icp: ["trader"]
content_type: "guide"
reading_time: "3 min"
last_reviewed: "2026-09-07"
last_verified: "2026-09-07"
volatile: true
prerequisites: ["20-subaccounts-api-wallets", "87-how-hyperliquid-api-signing-works"]
related: ["125-funds-subaccounts-api-wallets", "126-operational-controls-institutional-hyperliquid-trading"]
---

# Designing API Wallets for Hyperliquid Trading Systems

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.

## How this connects

Start with [Subaccounts and API Wallets](/hyperliquid-academy/article/20-subaccounts-api-wallets), [How Hyperliquid API Signing Works](/hyperliquid-academy/article/87-how-hyperliquid-api-signing-works) if the underlying concept is unfamiliar. Related reading: [How Funds Can Structure Hyperliquid Subaccounts and API Wallets](/hyperliquid-academy/article/125-funds-subaccounts-api-wallets), [Operational Controls for Institutional Hyperliquid Trading](/hyperliquid-academy/article/126-operational-controls-institutional-hyperliquid-trading).

## Sources

- https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets
- https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint