Hyperliquid MCP server setup

CoTrading editorial team 2026-09-16 Updated: 2026-09-23

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 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’s documentation does not say either way, and there is no prohibition to quote. Its official Python SDK signs withdrawals and transfers (withdraw3, usdSend, spotSend) with a different scheme from trading, and third-party integrations state that these require the master account’s key — but that is a third party describing the venue, not the venue committing to it. (An earlier version of this page argued it was a structural property of the signing scheme; that argument rested on a misreading of the SDK and was withdrawn on 2026-09-23.)

So test it on testnet with your own agent wallet before treating it as a security boundary. Even unconfirmed, a delegated signer 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. The budget is spent by actions — orders, cancels, modifications — not by info requests, and a batch of n orders counts as n, so an agent that places and cancels test orders on a new address can exhaust it before it has traded much, 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. Whether an agent wallet can sign withdrawals is not stated in Hyperliquid’s docs, so test it on testnet before relying on it — but a delegated signer is still 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.