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.

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

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