HyperliquidMCP

CI License: MIT Node HyperliquidMCP MCP server

Monetized MCP server for Hyperliquid analytics & signals. Gives AI agents (Claude, Cursor, ChatGPT, autonomous trading agents) the Hyperliquid analytics that free open-source MCP servers don't have — whale-cohort signals, liquidation maps, funding screeners, HIP-3 analytics, and ready-made risk reports — plus an optional local trading tier that attaches a builder code to orders.

⚠️ Analytics, not investment advice. Trading tools place real orders and are irreversible.

---

Tiers & tools

Free (open-source parity — the hook)

Tool	What it returns
hl_get_markets	Perp markets: mark/oracle price, hourly + annualized funding, OI, 24h volume; filter/sort
hl_get_orderbook	L2 book (top-N levels), spread, mid
hl_get_candles	OHLCV candles by interval/range or lookback
hl_get_funding_history	Funding history + avg/cumulative
hl_get_account	Positions, equity, margin, liquidation prices for any address
hl_get_open_orders	Open resting orders for any address

Premium (the differentiator — metered)

Tool	What it returns
hl_whale_positions	Aggregated cohort positioning by coin: net long/short, wavg entry, 1h/24h change
hl_whale_flow_alerts	Recent large cohort position shifts above a USD threshold
hl_liquidation_map	Liquidation clusters (notional-at-risk by distance from mark), nearest cascades
hl_funding_screener	Every perp screened by annualized funding + cross-venue spreads
hl_hip3_analytics	HIP-3 (builder-deployed / RWA / equity) perp metrics + external basis
hl_portfolio_risk	Liquidation distance, effective leverage, concentration, stress scenarios, PnL Sharpe
hl_vault_screener	Vaults by APR, max drawdown, Sharpe/Sortino, age, TVL, leader share
hl_trader_report	Wallet breakdown: winrate, avg R, PnL curve, scalp/swing style, top coins

Agent-native (v0.3) — the differentiators

Tool	Tier	What it does
hl_create_alert / hl_list_alerts / hl_delete_alert	premium	Register/manage standing alerts (funding threshold, price move, whale net-flip). The server evaluates them on a schedule — it watches the market for your agent.
hl_poll_alerts	premium	Retrieve fired alert events since your last poll (at-least-once), each with a signed signal payload.
hl_signal_track_record	premium	Transparent, verifiable performance of emitted signals: hit-rate and avg/median direction-adjusted forward return per signal type.
hl_request_free_key	free	Self-serve API key — one call, no signup, grants 100 premium calls/month. Send it as X-API-Key. This is the intended first call for any new agent: premium tools point at it by name when they need a key.
hl_signal_pubkey	free	Ed25519 public key to independently verify any signal's authenticity + timestamp.
hl_admin_stats	free (own gate)	Operator only — requires adminSecret matching HYPERSIGNAL_ADMIN_SECRET. Per-key usage this billing period, top tools, active alerts, signal track record, x402 payment counts.
hl_smart_money_score	premium	Rank a cohort by a smart-money screening score (risk-adjusted perf + winrate + reward/risk + size + activity) with behavioral labels (whale, sharp, scalper, market_maker_like, high_conviction, …). A descriptive screener over past results — see hl_score_calibration before treating it as a forecast.
hl_score_calibration	free	Out-of-sample evidence for the smart-money score: Spearman rank correlation between score and the realized forward PnL each wallet went on to earn, p-value, and mean forward PnL per score quartile. Free on purpose — a claim about predictive power should be checkable before you pay for it. The server scores its own cohort daily, so this fills in whether or not anyone is calling the paid tool.
hl_coordination_scan	premium	Find wallets holding near-identical exposure (cosine similarity) — likely the same entity / copy-bot / coordinated group; returns clusters + strongest pairs.
hl_polymarket_divergence	premium	Compare Polymarket price-threshold odds against the probability implied by Hyperliquid price + realized vol — a cross-market mispricing edge no other MCP offers.

Every emitted signal is cryptographically signed and scored against forward price — a track record that can't be cherry-picked. Persistence (alerts, positioning snapshots, signals) is SQLite-backed and survives restarts.

Trading (optional, local stdio only, builder code, maximum warnings)

Tool	What it does
hl_place_order	Limit/market order via your agent wallet, builder code attached
hl_cancel_order	Cancel by coin + order id
hl_close_position	Reduce-only market close
hl_approve_builder_fee_guide	Read-only — generates the approveBuilderFee payload/instructions for your main wallet
hl_twap_order	Slice a position into evenly-spaced child orders (TWAP) to minimize impact, builder code on each child
hl_copy_wallet	Mirror a target wallet's positioning scaled to your equity (copy-trading), builder code attached
hl_execution_status	Progress of running TWAP/execution plans

Trading defaults to dry-run (previews the exact signed action without sending). Submitting requires HL_ENABLE_TRADING=true + HL_AGENT_PRIVATE_KEY (env only) + confirm=true + dryRun=false. Trading tools are never exposed on the remote HTTP server.

---

Install

Requirements

Node 20 or 22 LTS (Node 24 has no prebuilt better-sqlite3 binaries and requires a C++ toolchain — use LTS). npm install && npm run build.

Local (stdio) — free + trading, for Claude Desktop / Claude Code / Cursor

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "hypersignal": {
      "command": "node",
      "args": ["/absolute/path/to/hypersignal-mcp/dist/server-stdio.js"],
      "env": {
        "HL_NETWORK": "mainnet",
        "HL_BUILDER_ADDRESS": "0xYourBuilderAddress",
        "HL_ENABLE_TRADING": "false"
      }
    }
  }
}

Cursor (.cursor/mcp.json) uses the same command/args/env shape.

Inspect locally:

npm run build && npm run inspect     # @modelcontextprotocol/inspector

Remote (Streamable HTTP) — free + premium, monetized

cp .env.example .env      # fill in keys / builder / x402
docker compose up -d      # serves POST /mcp on :8080, GET /healthz

Point an MCP HTTP client at https://your-host/mcp and send X-API-Key: <key> (or Authorization: Bearer <key>).

Node's built-in fetch only honors HTTPS_PROXY when NODE_USE_ENV_PROXY=1 (Node ≥ 22.21). Behind an egress proxy, set that env var.

---

Monetization

Tier	Limit	Price
anonymous (no key)	free tools only	—
free key	100 premium calls/month	$0
pro key	unlimited analytics	$19/mo
x402 pay-per-call	per premium call	$0.005–0.02 USDC on Base

• API keys — provision via HYPERSIGNAL_PRO_KEYS / HYPERSIGNAL_FREE_KEYS (comma-separated raw keys, hashed before storage in SQLite). Usage counters are per key, per month.
• x402 — when a request has no key/quota and X402_ENABLED=true, premium tools return an x402 payment-required response with requirements; after facilitator verification+settlement the call runs. Without a facilitator it fails closed (never fabricates a payment).
• Apify — apify-actor/ re-exports the best-selling premium tools as a pay-per-event Actor.

---

🔌 Builder code (connect our terminal config)

Route your Hyperliquid orders through HyperSignal's builder code to support the project: set HL_BUILDER_ADDRESS and (optionally) HL_BUILDER_FEE_TENTHS_BPS (tenths of a bp; default 5 = 0.5 bp, Hyperliquid perp cap is 10 bp). One-time approval from your main wallet:

hl_approve_builder_fee_guide   →  gives you the exact approveBuilderFee payload + steps

The server never sees your main key; you sign the approval yourself.

---

Architecture

src/
  core/       Hyperliquid Info client, WS mids feed (+REST fallback), LRU+TTL cache, rate limiter, retries
  hl/         typed endpoints, market/account/whale normalization, cohort resolution
  tools/      one file per tool (Zod input + outputSchema + annotations); free / premium / trading
  billing/    SQLite keys + monthly counters, tiers, x402 (fail-closed)
  trading/    L1 action signing (viem + msgpack), dry-run-first exchange service
  server-core.ts   builds an McpServer for a tier set + billing gate
  server-stdio.ts  local entrypoint  (free + trading)
  server-http.ts   remote entrypoint (free + premium, stateless JSON)
apify-actor/  thin pay-per-event wrapper
evals/        10 read-only, time-stable eval questions
docs/         PHASE0 research report, GTM checklist

Design rules enforced: no secrets outside .env; trading never remote; every external call has a timeout + 3 exponential retries + graceful degradation; responses are aggregated/paginated/truncated; premium/trading tools carry financial disclaimers; only Hyperliquid endpoints verified in Phase 0.

---

Development

npm run dev:stdio     # tsx, no build
npm run dev:http
npm run typecheck     # strict, no `any`
npm test              # offline unit tests (signing, stats, aggregation, cache)
npm run build

License

MIT. Not affiliated with Hyperliquid. Use at your own risk.