How Hyperliquid API Signing Works

Advanced | 5 min | Last verified 2026-09-10

How Hyperliquid API signatures are constructed, why valid-looking signatures fail, and how to debug signing against the official SDK.

Hyperliquid's trading API authenticates sensitive actions with cryptographic signatures rather than reusable API passwords. The difficult part is usually not ECDSA. It is reproducing the exact payload, serialization, signing scheme, nonce, and address normalization that Hyperliquid expects.

The official documentation recommends using an existing SDK rather than implementing signing from scratch because a mathematically valid signature can still authenticate the wrong payload.

Hyperliquid has two signing families

The official Python SDK separates sign_l1_action from sign_user_signed_action. They are not interchangeable.

L1 exchange actions such as orders use the L1 action signing path. Human-readable actions such as certain transfers use the user-signed path with their own domain and payload rules. Before debugging bytes or keys, first confirm that the action uses the correct signing family.

Serialization has to match exactly

For L1 action signing, MessagePack serialization is part of the signed message. The protocol documentation highlights several common sources of mismatches:

• Field order matters for MessagePack.
• Numerically equivalent values can serialize differently when trailing zeroes are preserved.
• Address casing matters. Hyperliquid recommends lowercasing addresses before signing and sending.
• The action, nonce, vault or subaccount context, and other fields used to build the payload must match what is sent to the API.

This is why changing 1 to 1.0, rebuilding an object in a different field order, or normalizing an address after signing can invalidate an otherwise correct implementation.

The error message often points to the wrong signer

A bad payload does not normally produce an error saying which byte is wrong. Hyperliquid recovers a signer from the submitted signature and payload. If the payload differs from what you intended to sign, the recovered address can be unrelated to your wallet.

Two documented symptoms are errors similar to:

• L1 error: User or API Wallet 0x... does not exist.
• Must deposit before performing actions. User: 0x...

If the address in the error is not the wallet or approved API wallet you expected, treat that as a signing-construction problem rather than immediately assuming the account is missing or unfunded.

Do not trust local signer recovery by itself

One subtle failure mode is recovering the expected signer locally and concluding the signature must be correct. The documentation warns that a local recovery routine can reconstruct the payload from the same incorrect assumptions as the signing routine.

A better test is to compare each intermediate value against the official Python SDK for the same known action.

A practical debugging sequence

1. Confirm whether the action uses sign_l1_action or sign_user_signed_action.
2. Reproduce one minimal known-good action with the official SDK.
3. Log the exact action object, nonce, and any vault or subaccount address before serialization.
4. Compare MessagePack bytes and hashes between your implementation and the SDK.
5. Remove trailing zeroes where the protocol expects canonical numeric strings.
6. Lowercase address fields before signing and sending.
7. Compare the server-recovered address in any error with the signer you intended to use.
8. Only after the payload matches should you investigate key permissions, registration, funding, or nonce state.

API wallets add another identity distinction

An approved API wallet signs on behalf of a master account or subaccount, but it is not the economic account whose positions and balances you usually query. Hyperliquid's nonce and API-wallet documentation specifically warns that querying account state with the agent/API-wallet address can return empty data.

Keep three identities explicit in production code: the master or subaccount whose state you want, the API wallet authorized to sign, and any vault or subaccount address attached to the action.

Use the SDK as a reference implementation

If you need a custom client in another language, treat the official Python SDK as a test oracle. Build fixtures that compare serialized payloads and signatures for representative orders, cancels, transfers, and account-management actions. This catches signing regressions before they reach production.

Continue with Hyperliquid Nonces and Replay Protection and Designing API Wallets for Hyperliquid Trading Systems.