Skip to content

Connection security

Hyperliquid API Wallet vs Master Address

Follow approval, signing and balance queries through three addresses to diagnose an empty Hyperliquid account read.

Ivory key linked by a lime cord to two ceramic file trays on a dark surface
Illustration for connection security; examples in this article are educational.

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.

IdentityPurpose in this explanationField or operation
Master account MApproves the agent; identifies the main accountApproval signer; user=M for main-account reads
Subaccount SIdentifies the intended subaccountuser=S for its reads; vaultAddress=S for ordinary subaccount orders
Agent ASigns authorized trading actionsagentAddress=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 stateAddress queriedEquity in the constructionWhat it establishes
Main-account readM4,000 USDCMain-account state
Intended subaccount readS1,000 USDCThe process's intended account state
Mistaken signer readA0 USDCNo 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.

  1. Query userRole for the supplied address. The documented agent response identifies its associated user in data.user; a subaccount response identifies its master in data.master.
  2. Retrieve subAccounts for M and reconcile the intended S with subAccountUser and master.
  3. Read the relevant account state for S, then compare positions and orders using that same identity and DEX scope. Retain the observation time.
  4. 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.

Keep the context with the example.

Each worked example is illustrative, with its sources and assumptions in the article. Read our editorial standards for authorship, verification and corrections.