Hyperliquid API setup and agent wallets
Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs.
Hyperliquid has no API key. Instead, a master account approves an API wallet — also called an agent wallet — that signs on its behalf.
If you are arriving from a centralised exchange, that one difference invalidates most of your mental model: there is no permission checkbox, no secret to rotate in the usual sense, and the thing you query is not the thing that signs.
| Purpose | URL |
|---|---|
| Mainnet | https://api.hyperliquid.xyz |
| Testnet | https://api.hyperliquid-testnet.xyz |
| EVM JSON-RPC | rpc.hyperliquid.xyz/evm |
The agent wallet model
The documentation is explicit: “A master account can approve API wallets to sign on behalf of the master account or any of the sub-accounts.”
And, crucially: “API wallets are only used to sign. To query the account data associated with a master or sub-account, you must pass in the actual address of that account.”
That second sentence is the one that produces the most common setup failure.
The empty-results trap
If your signing key is an agent wallet, you must also configure the account address as the master address. Otherwise the client queries the agent’s own address for balances, orders and events — and the agent’s address owns nothing.
The symptom is distinctive and misleading: orders are live on the venue, but order-status requests and WebSocket user feeds come back empty. Everything looks broken except the part that is working.
If you are seeing that, this is almost certainly it.
Expiry and replay
API wallets can expire, and expiry is one of the conditions under which nonce state is pruned.
The documentation carries a warning worth taking literally: once deregistered, nonce state may be pruned, potentially allowing previously signed actions to be replayed. Its guidance is to generate new wallets for future use rather than reusing addresses.
So the operational rule is: when you retire an agent wallet, retire the address. Do not re-approve it later. Treat it as burned.
Can an agent wallet move funds?
Hyperliquid’s documentation does not say. Neither the withdrawal section of the exchange endpoint page nor the signing page states whether an API wallet may sign fund-moving actions, so there is no prohibition to quote.
What can be said is narrower. The official Python SDK signs withdrawals and transfers through a different scheme from trading:
| Action | Signing scheme in the official SDK |
|---|---|
withdraw3 (withdraw from bridge) | user-signed typed data |
usdSend (USDC transfer) | user-signed typed data |
spotSend (spot transfer) | user-signed typed data |
Orders, cancels, leverage, vaultTransfer | L1 action signing |
Third-party integrations — NautilusTrader’s Hyperliquid documentation, for example — state that withdrawals and transfers require the master account’s own key. That is a useful signal, but it is a third party describing the venue’s behaviour, not the venue committing to it.
Correction, 2026-09-23. An earlier version of this page argued that an agent signature structurally cannot express a withdrawal, because trading signatures carry the master’s address and fund-moving signatures do not. On re-reading the SDK source that premise is wrong: the trading signature hashes only an optional vault address, and attribution to the master account happens on the exchange side. The structural argument has been withdrawn.
So treat “an agent wallet cannot withdraw” as unconfirmed by Hyperliquid. If your security model depends on it, test it on testnet with your own agent wallet before relying on it, and keep the master key out of any process that does not need it.
Rate limits — and the one that catches new accounts
Per IP:
| Limit | Value |
|---|---|
| REST requests | 1200/minute, weighted by request type and batch size |
| WebSocket connections | 10 |
| New WebSocket connections | 30/minute |
| WebSocket subscriptions | 1000 |
| Messages sent | 2000/minute |
| EVM JSON-RPC | 100 requests/minute |
Per address — this is the unusual one:
| Limit | Value |
|---|---|
| Request allowance | 1 request per 1 USDC traded cumulatively since address inception |
| Initial buffer | 10,000 requests |
| Open orders | 1000 default, +1 per 5M USDC volume, capped at 5000 |
A brand-new address has only the initial buffer, no matter how generous the IP
limit looks. The address budget is spent by actions — orders, cancels,
modifications — not by info requests, and a batch of n orders counts as n.
A client that places, cancels and re-places orders before it has traded much
can exhaust the buffer, and then appear broken.
This is the single most surprising operational property of the venue, and it is not something most people think to check. If a new Hyperliquid integration starts failing for no apparent reason, look here before anything else.
The design intent is legible enough — request budget is earned by using the venue — but it inverts the usual assumption that a fresh account is unconstrained.
Setup checklist
- Master account approves an API wallet
- Client configured with the agent’s private key for signing
- Client configured with the master’s address for queries — the empty- results trap
- Testnet first at
api.hyperliquid-testnet.xyz - Agent wallet expiry recorded somewhere you will see it
- Address-based request budget understood for a new account
- Retired agent addresses marked never-reuse
FAQ
Does Hyperliquid have API keys?
No. A master account approves an API wallet (agent wallet) that signs on its behalf. There is no key/secret pair and no permission checkboxes, so advice written for centralised exchanges does not transfer directly.
Why are my Hyperliquid order queries returning empty?
Almost certainly because the client is querying the agent wallet’s address rather than the master’s. The documentation states that API wallets are only used to sign, and that querying account data requires the actual address of the master or sub-account. Orders will be live on the venue while status requests and user feeds come back empty.
Can an API wallet withdraw my funds?
Hyperliquid’s documentation does not say. Its official SDK signs withdrawals and transfers with a different scheme from trading, and third-party integrations state that these require the master account’s key, but the venue itself has not committed to it. Test it on testnet with your own agent wallet before treating it as a security boundary.
Why does my new account run out of API requests so quickly?
Because request allowance is earned by trading volume — one request per 1 USDC
traded cumulatively, on top of an initial 10,000-request buffer. A new address
has only the buffer, and every order, cancel or modification spends it — a
batch of n orders counts as n. Info requests count against the IP limit, not
the address budget, so the usual culprit is a client that re-quotes or
cancel-replaces heavily on a new address.