A Hyperliquid API wallet, also called an agent wallet, signs authorized actions for a master account or its subaccounts. The master address identifies the main account; a subaccount has its own address. Read balances and positions using the address of the account you intend to inspect. An empty response for an agent address can mean you queried the signer instead of that account.
A valid trading credential and a correct balance query answer different questions. Hyperliquid's documentation, checked on 29 October 2026, explicitly describes empty agent-address reads as a common mistake. Its API wallet documentation separates signing authority from the account being inspected. Before treating a zero balance as missing money, trace both identities through the request.
Keep the master, subaccount and agent separate
The master is the account that approves the agent. A subaccount is a separate target under that master. The agent is the signing identity used by an authorized process.
| Identity | Purpose in this explanation | Field or operation |
|---|---|---|
| Master account M | Approves the agent; identifies the main account | Approval signer; user=M for main-account reads |
| Subaccount S | Identifies the intended subaccount | user=S for its reads; vaultAddress=S for ordinary subaccount orders |
| Agent A | Signs authorized trading actions | agentAddress=A in approval; agent key for later signatures |
The exchange endpoint reference says subaccounts do not have private keys and uses vaultAddress to select a subaccount or vault for these order requests. An approved API wallet can sign on the master's behalf. These facts fit together: S identifies the account affected, while M or its approved agent supplies the signature.
Creating another agent therefore does not create another allocation of trading capital. The subaccount boundary worksheet develops that financial distinction. Here, the practical task is to ensure that the same intended account survives approval, order construction and observation.
Approval authorizes the signer
The documented approveAgent action identifies the agent address and can include an agent name. Its inner nonce must match the outer request's nonce. The approval establishes the relationship used for delegated signing; it does not instruct an application to move account balances into the agent address. Official approval fields.
The official Python SDK makes the two signing stages visible. In the inspected snapshot, approve_agent creates an agent key and address, then signs the approval with the wallet held by that Exchange instance. Later, bulk_orders uses its configured wallet to sign an order action. With an agent-based trading client, that later wallet is A. Pinned SDK approval and order implementation.
Keep the intended scope explicit. A process configured to target S is an application configuration choice. It does not, by itself, prove that the master's agent authorization is restricted to S. Separate credentials and separate balances must each be checked on their own terms.
A hypothetical 5,000-USDC identity trace
Consider a constructed account with these artificial addresses:
- M is
0x1111111111111111111111111111111111111111. - S is
0x2222222222222222222222222222222222222222. - A is
0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.
These addresses are teaching labels, not deposit destinations. Assume M has 4,000 USDC of account equity and S has 1,000 USDC. A has no trading balance. The example uses Manual / Standard mode on the default native USDC perpetual DEX, with no spot holdings, positions or open orders. This mode has separate spot, perpetual and DEX balances in the official account-mode definitions. Fees, funding, transfers and price changes are absent during the trace.
First, M approves A. The modeled balances remain 4,000, 1,000 and zero. Next, a process prepares an ordinary order for S, with A as signer and S as the subaccount target. This construction is not submitted; the point is to inspect its identities before any action changes the ledger.
Then the process tries to load its starting account state. A developer obtains the address from the agent's key and accidentally sends that address as the read request's user.
| Observation at the same modeled state | Address queried | Equity in the construction | What it establishes |
|---|---|---|---|
| Main-account read | M | 4,000 USDC | Main-account state |
| Intended subaccount read | S | 1,000 USDC | The process's intended account state |
| Mistaken signer read | A | 0 USDC | No balance at the queried signer address |
The correct group total is still 4,000 + 1,000 + 0 = 5,000 USDC. Choosing A for the display omits 1,000 USDC from the intended subaccount view, or 100% of that view's balance. It changes no account balance.
Replacing A with M is also an incomplete repair when the process should trade S. The display would show 4,000 USDC, which is 3,000 more than S's assumed equity. A nonzero answer can conceal a wrong target just as easily as a zero answer can expose one.
These numbers reconcile only this construction's ledger. They do not represent live Hyperliquid responses or available withdrawal amounts. The cross-versus-isolated margin explanation covers the separate question of which collateral supports an open position.
Map the write target to the read identity
For the hypothetical subaccount order, retain A as signer and set the ordinary order's vaultAddress to S. To inspect S, send clearinghouseState with user=S and the intended dex. This /info account-summary request does not require an agent signature. For the default perpetual DEX, the documented dex value is an empty string. Perpetual account-summary request.
The target belongs in the signed order construction. The pinned SDK's action_hash includes whether a vault/subaccount address is present and, when present, its address bytes. Changing that target after signing changes the payload being authenticated. Build and sign for the selected target together. Pinned L1 signing implementation.
This mapping concerns ordinary L1 order actions. Other action families have their own fields and signing paths; copying vaultAddress into every request is not a general targeting method.
The account read also needs the correct financial scope. The perpetuals reference directs readers of trading-account balances under unified account or portfolio margin to the spot balances endpoint. A correctly identified account can still look incomplete when the reader chooses the wrong balance schema.
For a builder-deployed market, retain the correct account identity and also resolve its DEX context. The HIP-3 versus native perpetuals guide explains why an account address alone does not select every market context.
Check the Python example's empty-address fallback
The SDK README tells API-wallet users to configure the agent's secret alongside the main wallet's public account address. Those fields have different jobs. Pinned SDK configuration instructions.
The inspected example_utils.setup helper reads account_address. If it is blank, the helper substitutes the address derived from the signing key. With an agent secret, that fallback is A. The helper then reads perpetual and spot state for that address and can stop with a no-equity message. Its diagnostic explicitly mentions the possibility of an API wallet address being supplied. Pinned setup helper.
That is a useful explanation for this particular failure. It is not a complete account-mode validator.
Also inspect explicit read calls. Info.user_state(address, dex) sends its supplied address as user; it does not inspect a separate Exchange object's account setting to infer your intent. Setting account_address=M somewhere else cannot repair a call that explicitly passes A. Pinned Info request construction.
Validate a zero result with a short read-only sequence
Start with a record containing the environment, M, intended target, A, account mode and DEX context. Compare full address values with the official interface; abbreviated display names are insufficient for this check.
- Query
userRolefor the supplied address. The documented agent response identifies its associated user indata.user; a subaccount response identifies its master indata.master. - Retrieve
subAccountsfor M and reconcile the intended S withsubAccountUserandmaster. - Read the relevant account state for S, then compare positions and orders using that same identity and DEX scope. Retain the observation time.
- If the read remains empty, check the network, account mode and balance endpoint before changing credentials or funding anything.
These are proposed validation steps using the official role and subaccount schemas. An empty order list alone cannot establish an empty balance. A role response also does not prove that every proposed trading action will be accepted.
Preserve the returned decimal strings when comparing state. The API decimal-precision guide shows why rounding or coercion can create an additional discrepancy after the address has been corrected.
Keep signature failures separate from empty reads
An exchange rejection containing an unexpected signer address needs a payload investigation. Hyperliquid's signing guidance describes incorrect signatures recovering another address and distinguishes L1 from user-signed actions. Compare the exact action, target, environment and serialization with the inspected SDK. A balance query for A does not diagnose that signing failure.
Nonce tracking follows the signer too. Two subaccounts sharing A also share A's nonce state. The signer-nonces versus timestamps guide follows that coordination problem. The official wallet guidance also warns against reusing old agent addresses after deregistration because nonce state may be pruned.
When replacing an agent, update the signing credential while preserving the verified account target and read identity. Recheck M, S and the new agent as separate values. The intended subaccount's balance, positions and order records should remain attached to S throughout that handoff.
