hyperliquid-agent-gateway

An MCP (Model Context Protocol) server that gives AI agents read-only, keyless access to Hyperliquid public data - the ~233-perp DEX market, ~326 spot pairs, funding, per-account risk and HyperEVM (chain 999) token transfers. No API keys, no auth, no signing, no writes: every tool reads public endpoints only (api.hyperliquid.xyz/info and rpc.hyperliquid.xyz/evm), cached and rate-limited so an enthusiastic agent cannot hammer the upstream.

Use cases

• Watch a wallet's risk — per-account margin summary, leverage, liquidation distance on any address (account risk view)

• Fund the carry, not the noise — funding history + carry screener across 233 perps to find stable paid positions

• Trace HyperEVM flows — token transfers on chain 999 tied back to the perp markets (token_transfers)

• Read the book before you enter — order book + recent trades + all-mids in one pass

• Trader scouting — activity of any address: positions, volume, what they actually trade

Full walkthroughs: examples/use-cases.md.

Quickstart

stdio (default, for local agents):

uvx hyperliquid-agent-gateway

or from a checkout:

git clone https://github.com/alekskram/hyperliquid-agent-gateway
cd hyperliquid-agent-gateway
uv sync
uv run hyperliquid-agent-gateway

Claude Desktop / Cursor config:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["--from",
               "git+https://github.com/alekskram/hyperliquid-agent-gateway",
               "hyperliquid-agent-gateway"]
    }
  }
}

Hosted form - streamable HTTP on port 8903:

uv run hyperliquid-agent-gateway --http            # 127.0.0.1:8903
curl 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, os
p = 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

Hosted form — streamable HTTP on port 8903:

uvx hyperliquid-agent-gateway --http

Tools

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

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 additionally 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.

License

MIT.