Hyperliquid MCP server setup

2026-11-12

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 keys, so every piece of “restrict your key permissions” advice has no direct translation here. What it has instead is a signing delegation: a master account approves an API wallet (agent wallet) to sign on its behalf.

That difference is the whole story for MCP setup, because most Hyperliquid MCP servers ask for a raw private key in your client’s config block — and whether that key is a master wallet or a delegated agent changes what a compromise costs by an enormous margin.

The three postures available

1. No key at all. alekskram/hyperliquid-agent-gateway is read-only and keyless — market data, funding, per-account risk, no auth, no signing, no writes. All 12 of its tools are annotated readOnlyHint: true.

Worth a note: that annotation is correct usage here, and it is still not a security boundary you should rely on from a server you have not audited. The MCP schema states annotations “are not guaranteed to provide a faithful description of tool behavior” — see read-only vs trade permission in an MCP setup. What makes this server safe is that it holds no key, not that it says so.

2. A delegated agent wallet. edkdev/hyperliquid-mcp is the one that documents Hyperliquid’s agent mode explicitly:

HYPERLIQUID_PRIVATE_KEY      # the API wallet's key — signs
HYPERLIQUID_ACCOUNT_ADDRESS  # the master account — queried
HYPERLIQUID_TESTNET          # "true" | "false"
HYPERLIQUID_VAULT_ADDRESS    # optional, vault trading

Its stated rationale: “Keep your main account safe while allowing an API wallet to trade.” The wallet must be approved as an agent through the Hyperliquid UI first.

3. A raw master key. Several servers take one. This is the posture to avoid if a delegated alternative exists, for the reason in the next section.

Why the delegation matters

Hyperliquid’s documentation states that “API wallets are only used to sign”, and that querying account data requires passing the master or sub-account’s actual address — the agent’s own address owns nothing.

Can an agent wallet move funds? Hyperliquid does not say either way, and there is no prohibition to quote. What its official Python SDK shows is structural: the fund-moving actions (withdraw3, usdSend, spotSend) are user-signed and take no account or vault address, while trading actions go through the L1 signing path that does. That address field is how an agent’s signature is attributed to the master. Without it, there is no way to express “move the master account’s funds” in the signed payload.

So the practical position is that 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 — but it is the closest thing to a trade-only credential the venue offers, and it is clearly better than handing a master key to third-party code.

The setup mistake everyone makes

If the signing key is an agent wallet, you must also set the account address to 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.

In edkdev/hyperliquid-mcp that is HYPERLIQUID_ACCOUNT_ADDRESS. If you are seeing empty results, check it before anything else. Full detail in Hyperliquid API setup and agent wallets.

Install

uvx --from mcp-hyperliquid hyperliquid-mcp      # recommended
# or
pip install mcp-hyperliquid && mcp-hyperliquid

23 tools: account, orders (including bracket orders — atomic entry plus take-profit and stop-loss), trading history, market data, vaults, utility.

Testnet at https://app.hyperliquid-testnet.xyz with a faucet. Set HYPERLIQUID_TESTNET=true and use it first — Hyperliquid’s testnet is a separate hostname, so credentials do not cross over.

The README’s guidance is sound and worth repeating: never commit private keys, test on testnet first, use agent mode for production, and start with minimum order sizes.

Two operational traps

The address-based request budget. Hyperliquid grants 1 request per 1 USDC traded cumulatively since address inception, with an initial buffer of 10,000 requests — separate from the 1200/minute IP limit. A new account has only the buffer, so a model doing exploratory reads can exhaust it without placing a single trade, and then appear broken.

This is the single most surprising property of the venue and it is not something most people think to check. If a new Hyperliquid MCP setup starts failing for no apparent reason, look here first.

Retired agent wallets are burned. Once deregistered, the documentation warns that nonce state may be pruned, potentially allowing previously signed actions to be replayed, and advises generating new wallets rather than reusing addresses. So the incident procedure differs from a CEX: deregister, and do not reuse that address — see what to do if an API key leaks.

FAQ

Does Hyperliquid have an official MCP server?

We did not find one — several community projects exist, of varying quality and posture. That means we did not find one rather than that none exists. Among the community options, the meaningful distinction is whether a server uses Hyperliquid’s agent-wallet delegation or asks for a raw master private key.

What is agent mode and why should I use it?

A master account approves an API wallet to sign on its behalf, so the key held by the MCP server is a delegated signer rather than your main wallet. Because fund-moving actions carry no account address in Hyperliquid’s signing scheme, there is no way for an agent signature to express moving the master’s funds — a structural property rather than a permission flag, and much better than handing over a master key.

Why are my Hyperliquid MCP queries returning empty results?

Almost certainly because the account address is not set to the master account. API wallets are only used to sign; querying account data requires the master or sub-account’s actual address, and the agent’s own address owns nothing. Orders will be live on the venue while status requests and user feeds come back empty.

Can I use a Hyperliquid MCP server without a private key?

For read-only use, yes — alekskram/hyperliquid-agent-gateway is keyless, covering market data, funding and per-account risk with no auth and no writes. It holds no credential at all, which is a stronger safety property than any configuration flag.