Hyperliquid Agent Gateway

hyperliquid-agent-gateway

[CI] [PyPI] [PyPI downloads] [MCP Catalog] [License: MIT] [Python 3.11+]

Hyperliquid puts about 233 perps, 326 spot pairs and a whole EVM chain in front of you, all readable through public endpoints. This MCP server does the reading for your agent: market and funding data, per-account risk, trader activity, HyperEVM (chain 999) token transfers. No keys, no signing, no writes; everything goes through api.hyperliquid.xyz/info and rpc.hyperliquid.xyz/evm, cached and rate-limited so an enthusiastic agent cannot hammer the upstream.

Use cases

The liquidation tool is the one people come for. Feed it any address and you get the margin summary, per-position leverage, and the distance to liquidation; when the venue publishes liquidationPx you get the real number, flagged as such, and when it doesn't you get an estimate that says it is one. We tested it on a $209M-notional 25x short book the day it was 17.6% from the cliff.

Funding: funding_carry_screener ranks all 233 perps from a single call and then fetches 168h of history only for the top few, because the API's weight budget (1200/min) punishes naivety. You see whether a rate is a spike or a regime.

HyperEVM transfers tie on-chain flow back to the perp markets; quote returns a book-derived mid that never leaves [bid, ask]; trader_activity dissects any address into fills, fees, win-rate, funding drag and open positions.

Full walkthroughs: examples/use-cases.md.

Quickstart

Claude Code:

claude mcp add hyperliquid -- uvx hyperliquid-agent-gateway

stdio (default, for local agents):

uvx hyperliquid-agent-gateway

or from a checkout:

git clone https://github.com/alekskram/hyperliquid-agent-gatewaycd hyperliquid-agent-gatewayuv syncuv run hyperliquid-agent-gateway

Claude Desktop / Cursor config:

{  "mcpServers": {    "hyperliquid": {      "command": "uvx",      "args": ["hyperliquid-agent-gateway"]    }  }}

Hosted form, streamable HTTP on port 8903:

uvx hyperliquid-agent-gateway --http             # 127.0.0.1:8903curl http://127.0.0.1:8903/health   # -> {"ok": true, "service": "hyperliquid-agent-gateway", ...}

[mcp_servers.hyperliquid]command = "uvx"args = ["hyperliquid-agent-gateway"]

# 1) start the gateway (keep it running)uvx hyperliquid-agent-gateway --http --port 8903 &
# 2) register it (merges into ~/.zcode/cli/config.json)python3 - <<'PY'import json, osp = os.path.expanduser("~/.zcode/cli/config.json")os.makedirs(os.path.dirname(p), exist_ok=True)cfg = json.load(open(p)) if os.path.exists(p) else {}cfg.setdefault("mcp", {}).setdefault("servers", {})["hyperliquid"] = {    "type": "http", "url": "http://127.0.0.1:8903/mcp"}json.dump(cfg, open(p, "w"), indent=2)print("hyperliquid-agent-gateway registered:", p)PY

Tools

All 12 tools are read-only (annotated readOnlyHint: true, destructiveHint: false, openWorldHint: true).

Why a gateway and not the raw API?

api.hyperliquid.xyz/info is open and one POST away. The traps start after that:

Rate limits

Two independent, locally enforced budgets protect the upstream:

/info - 1200 weight per rolling 60s (Hyperliquid's documented weight pricing), tracked per request type:

When the next request would exceed the budget the client waits once (<=5s) for the window to roll, then raises a clear error naming the limit - it never sleep-blocks forever.

HyperEVM RPC - 100 requests per rolling 60s (flat 1 per request), enforced separately from /info. Over-budget calls raise immediately (rpc-limit) - tools surface an honest error dict, and wallet_balance stops its ERC-20 scan at the cap.

TTL caches also dedupe repeated calls per data type: allMids 15s, recentTrades 15s, l2Book 5s, metaAndAssetCtxs 60s, spotMeta 3600s, spotMetaAndAssetCtxs 60s, candleSnapshot 300s, fundingHistory 300s, per-address account types 60s.

Data notes

• Every numeric from the API is a STRING upstream; the gateway parses them with a never-raising helper - null always means "not available", never zero.
• Every upstream failure returns an error dict {"error": ..., "source": ..., "reason": ...}, never a traceback; partial data degrades field-by-field with warnings[].
• liquidation_risk never invents a liquidation price: when the venue publishes none, liq_px stays null and the distance is an explicitly flagged estimate (formula in the tool's note). Mark px is likewise never invented: live positions carry no markPx, so it is resolved from metaAndAssetCtxs (fallback allMids) and the row's mark_px_source says which; no source -> null.
• funding_drag / funding_net: the venue's userFunding returns only NON-ZERO funding events, so a live null/empty for a fresh or quiet address is expected behaviour, not a bug.
• ERC-20 amounts use a static decimals map for canonical HyperEVM tokens (6 for USDC/USDT-style, 18 for PURR/HYPE); unknown tokens assume 18 and every row says decimals_source: "assumed_18" - do not trust 6dp precision for unmapped tokens.
• Cached responses carry age_seconds / fetched_at freshness fields.

Part of the suite

Four sibling read-only MCP gateways, one style: keyless, cached, honest degradation.

All four are on glama.ai and PyPI; any of them installs with uvx <name>.

License

MIT.