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 before acting on a number.
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?
The practical answer is no, and the reasoning is structural rather than a permission setting — worth understanding rather than memorising.
Hyperliquid’s own documentation does not state a prohibition. What its official Python SDK shows is that the fund-moving actions are implemented differently from trading:
| Action | Signing path | Carries an account/vault address? |
|---|---|---|
withdraw3 (withdraw from bridge) | user-signed | No |
usdSend (USDC transfer) | user-signed | No |
spotSend (spot transfer) | user-signed | No |
| Trading actions | L1 signing | Yes |
That address field is the mechanism by which an agent’s signature is attributed to the master account. Fund-moving actions do not have it — so there is no way to express “move the master account’s funds” in the signed payload. The signature is bound to the signing address, and the agent’s address owns nothing.
Write this down accurately if you are relying on it. The signing scheme gives an agent wallet no way to express a withdrawal of the master’s funds. Hyperliquid has not published this as a guarantee, so verify it against your own setup before treating it as a security boundary.
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. An automated client doing exploratory reads can exhaust 10,000 requests without placing a single trade, 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?
The signing scheme gives it no way to express that: fund-moving actions
(withdraw3, usdSend, spotSend) are user-signed and carry no account
address, so there is no field in which to name the master account. Hyperliquid
has not documented this as a guarantee, so verify it on your own setup rather
than relying on it blindly.
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, so exploratory polling can exhaust it before any trading happens. The 1200/minute IP limit is separate and does not help.