Hyperliquid MCP Server

HyperSignal MCP

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)

Premium (the differentiator — metered)

Agent-native (v0.3) — the differentiators

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.

Public proof, no key needed: the hosted server runs its own standing alerts (funding extremes on the top 10 perps by open interest, whale-cohort flips on BTC/ETH) and publishes their track record together with the score calibration and the signing key at /track-record (JSON). The same data is available to MCP clients as resources (hypersignal://about, ://track-record, ://calibration, ://signal-pubkey), plus three prompts: whale_briefing, wallet_risk_check, funding_carry_scan.

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

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. Every non-reduce-only order (including each TWAP slice and copy-trade leg) is capped at HL_MAX_ORDER_NOTIONAL_USD (default $10,000), which only the operator can raise. HIP-3 coins (xyz:XYZ100) trade on their builder dex, which keeps its own collateral (enable the unified account or transfer collateral to it) and may charge higher fees. Live HIP-3 orders also need HL_ENABLE_HIP3_TRADING=true: turn it on after a testnet run. Copy-trading mirrors main-dex positions only. Trading tools are never exposed on the remote HTTP server.

---

Try it on the hosted server

Nothing to install. Free tools work without a key. For the premium tools, call hl_request_free_key once: it returns a key with 100 premium calls a month, no signup.

Claude Code:

claude mcp add --transport http hypersignal https://hypersmash.fly.dev/mcp --header "X-API-Key: <your key>"

Cursor (.cursor/mcp.json):

{ "mcpServers": { "hypersignal": { "url": "https://hypersmash.fly.dev/mcp", "headers": { "X-API-Key": "<your key>" } } } }

Without a key the free tools still work; add the key after hl_request_free_key has issued one.

---

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), from npm:

{
  "mcpServers": {
    "hypersignal": {
      "command": "npx",
      "args": ["-y", "hypersignal-mcp"],
      "env": {
        "HL_NETWORK": "mainnet",
        "HL_BUILDER_ADDRESS": "0xYourBuilderAddress",
        "HL_ENABLE_TRADING": "false"
      }
    }
  }
}

From a clone instead: "command": "node", "args": ["/absolute/path/to/HyperliquidMCP/dist/server-stdio.js"]. 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.

---

Pricing

How to get each

• Free key: call hl_request_free_key. Instant, no signup.
• x402 pay-per-call: on the hosted server a premium call without a key answers with x402 payment requirements (0.01 USDC on Base, exact scheme); an x402-capable client signs the payment, retries with the X-PAYMENT header, and the call runs. The payment is settled only after the tool has delivered, so a failed call costs nothing.
• Pro: call hl_buy_pro. It answers with x402 payment requirements ($29 in USDC on Base); an x402-capable client pays and retries with the X-PAYMENT header, and the answer carries your Pro key, valid for 30 days (shown once: keep it). Call it again with your key in X-API-Key to add 30 days to its end; a free key is upgraded in place and keeps its alerts. The key is activated before the payment is settled and a renewal only after, so a payment that fails costs nothing. Payments are final, there are no automatic refunds: if something went wrong, open an issue with the time of the payment. Without an x402 client, open an issue titled "Pro key request" instead and say how to reach you; never post a key in an issue. When a Pro key runs out it works like no key (free tools, x402 per call) and the error says how to renew; its alerts keep running for now.

For operators

• API keys: provision via HYPERSIGNAL_PRO_KEYS / HYPERSIGNAL_FREE_KEYS (comma-separated raw keys, hashed before storage in SQLite; they never expire). Bought keys live in the same table with an end date, and every purchase is recorded in pro_purchases. Usage counters are per key, per month. A key removed from these lists is revoked on the next start, as long as at least one key stays listed: two empty lists read as a lost secret and revoke nothing.
• 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. It is private for now.

---

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