Skip to main content
Glama
Hydromancer MCP

Hydromancer MCP

by joshavenue

Hydromancer MCP

Ask your AI about Hyperliquid in plain English, using live data from the Hydromancer API.

Disclosure: this package is maintained by the Hydromancer team. You need a Hydromancer API key to use it.

"What is this wallet holding, and is it a good trader?" "Who were the best traders this week, without bots?" "Who got liquidated in the last 6 hours?" "How much BTC can I sell before the price moves 0.5%?"

Your AI picks the right tool, calls Hydromancer and explains the answer. You don't need to read API docs, write code or work out timestamps.

  • 19 read-only tools: wallets, trades, top traders, markets, liquidations, builders, prediction markets

  • Works with any MCP app: Claude Desktop, Claude Code, Cursor, Codex, VS Code (Copilot), Gemini CLI, Windsurf, Cline and others

  • Friendly inputs: coin names in any case (btc, $ETH, ETH-PERP, xyz:tsla), times like 24h, 7d or 2026-10-01

  • Safe: read-only. It cannot place, cancel or sign orders, and it never touches funds or private keys

  • Your key stays local: it is read from your app's settings and never sent anywhere except api.hydromancer.xyz (or api-testnet.hydromancer.xyz if you set it)

1. Get a Hydromancer API key

See Get API keys. Early-stage teams may qualify for free access.

Related MCP server: Coinversaa Pulse

2. Add it to your AI app

You need Node.js 20 or newer. Replace YOUR_KEY with your key.

Claude Desktop

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "hydromancer": {
      "command": "npx",
      "args": ["-y", "hydromancer-mcp"],
      "env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add hydromancer -e HYDROMANCER_API_KEY=YOUR_KEY -- npx -y hydromancer-mcp

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project): use the same mcpServers block as Claude Desktop.

Codex

~/.codex/config.toml:

[mcp_servers.hydromancer]
command = "npx"
args = ["-y", "hydromancer-mcp"]
env = { HYDROMANCER_API_KEY = "YOUR_KEY" }

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "hydromancer": {
      "command": "npx",
      "args": ["-y", "hydromancer-mcp"],
      "env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }
    }
  }
}

From a local copy

git clone https://github.com/joshavenue/Hydromancer-MCP && cd Hydromancer-MCP
npm install && npm run build

Then use "command": "node" and "args": ["/full/path/to/Hydromancer-MCP/dist/index.js"].

3. Ask

Try:

  • Give me an overview of wallet 0x… and tell me if it's a good trader.

  • Show the top 10 traders by profit over the last 7 days, no bots, then what the top 3 hold right now.

  • Which of these wallets have more than $1M: 0x…, 0x…, 0x…?

  • Who got liquidated on Hyperliquid in the last 6 hours? Longs or shorts?

  • BTC, ETH and HYPE: price, 24h volume and open interest.

  • Has ETH open interest been rising or falling today?

  • What's the BTC funding rate averaged over the last week, annualized?

  • How much did builder 0x… earn in fees in the last hour?

Tools

Tool

What it answers

hydromancer_wallet_overview

Balance (correct for unified-account and portfolio-margin wallets), account mode, open positions (entry, liquidation price, leverage, PnL), spot balances, trading record, bot score

hydromancer_compare_wallets

Up to 1,000 wallets at once, with balance and account mode, sorted by balance

hydromancer_wallet_trades

Fills in a time window, with volume, PnL, fees and per-coin totals

hydromancer_wallet_closed_trades

Round-trip trades: win rate, net PnL, hold time, best coin

hydromancer_wallet_open_orders

Resting limits, stop-losses, take-profits

hydromancer_wallet_transfers

Deposits, withdrawals, sends, vault moves, liquidations

hydromancer_wallet_funding

Funding paid or received, per coin

hydromancer_top_traders

Leaderboard by profit, win rate or volume, with bot and activity filters

hydromancer_market_snapshot

Price, 24h volume and open interest (max leverage in the top-markets list)

hydromancer_price_history

Candles from 1 second to 1 month (including 15s and 30s)

hydromancer_funding_history

Funding rates, average and annualized

hydromancer_open_interest_history

Open interest trend, 1 minute to 1 month buckets

hydromancer_recent_liquidations

Liquidations by market, with long/short totals

hydromancer_market_depth

Order book depth and slippage for a trade size

hydromancer_list_markets

Every market, HIP-3 exchanges, search by name or category

hydromancer_builder_activity

Volume, users and fees for a builder app

hydromancer_prediction_markets

Settled HIP-4 prediction markets

hydromancer_my_usage

Your own API usage and tokens

hydromancer_raw_request

Any other Hydromancer /info request

The server also provides a hydromancer_guide prompt and a hydromancer://guide resource that tell the AI which tool to use for which question.

Settings

Variable

Default

Purpose

HYDROMANCER_API_KEY

(required)

Your API key

HYDROMANCER_BASE_URL

https://api.hydromancer.xyz/info

API endpoint. Only the mainnet and testnet Hydromancer hosts are accepted.

HYDROMANCER_TIMEOUT_MS

30000

Request timeout

HYDROMANCER_MAX_RESULT_CHARS

40000

Cap on one tool result, so the AI is not flooded

Good to know

  • Each tool call uses your Hydromancer plan's tokens, like any API request. Check usage with hydromancer_my_usage.

  • Mainnet only. HIP-3 markets use a prefix, for example xyz:TSLA.

  • Balances: unified-account and portfolio-margin wallets keep their money in spot, so balanceUsd uses their spot stablecoins. Other spot tokens are listed but not priced.

  • Times are UTC. Some endpoints cap a single request (for example 2,000 fills); the tool says so when it happens.

Development

npm install
npm run build
npm test                                   # offline unit tests
HYDROMANCER_API_KEY=... npm run smoke      # calls every tool against the live API

From the Hydromancer blog

Guides and research on getting and using Hyperliquid data:

License

MIT

Available Tools

19 tools
hydromancer_builder_activityBuilder app activity (trades routed through an app)A
Read-only

Fills routed through a builder (a trading app such as MetaMask, Phantom or a Telegram bot) by its builder address, with volume, builder fees earned, unique traders and top coins. Default window: last 1h (busy builders produce thousands of fills). since/until accept Relative ("30m", "6h", "24h", "7d"), a date ("2026-10-01"), a date-time ("2026-10-01T12:00:00Z"), "now", or Unix ms.

Inputs: builder (required), limit, since, until.

hydromancer_compare_walletsCompare many wallets at onceA
Read-only

Look up balance, account mode and open positions for up to 1,000 wallets (100 when includeHip3=true), sorted by balance. Handles unified-account and portfolio-margin wallets, whose money sits in spot rather than perps. Use for watchlists: "which of these wallets are whales?", "what do these 50 traders hold?".

Inputs: addresses (required), includeHip3, minBalanceUsd.

hydromancer_funding_historyFunding rate history for a marketA
Read-only

Hourly funding rates for a market over time, with the average and annualized rate. Positive funding means longs pay shorts. Default window: last 7 days.

Inputs: coin (required), since, until.

hydromancer_list_marketsList every market and HIP-3 exchangeA
Read-only

Lists every tradable perp market, optionally filtered by search text or category (crypto, stocks, indices, commodities, fx), plus the HIP-3 exchanges (perp DEXs) that list stocks and other assets. Use when unsure of a market's exact name.

Inputs: limit, search, category.

hydromancer_market_depthOrder book depth and slippageA
Read-only

How much can be bought or sold near the current price. Returns USD depth on each side within 0.1% to 2% of the price for a market, plus the expected slippage for a market order of a given size over time.

Inputs: coin (required), since, orderSizeUsd.

hydromancer_market_snapshotLive price, volume and open interest for marketsA
Read-only

Current mark/oracle/mid price, 24h volume and open interest (in coins and USD) for one or more markets. The top-markets list also shows max leverage. Leave coins empty for the top markets by 24h volume. Works for HIP-3 markets (e.g. "xyz:TSLA").

Inputs: top, coins.

hydromancer_my_usageMy Hydromancer API usageA
Read-only

Your own Hydromancer API usage by day and request type: requests, failures, speed and billable tokens. Use to check how much of your plan you are using.

Inputs: days.

hydromancer_open_interest_historyOpen interest historyA
Read-only

How open interest (total open positions) in a market changed over time, in coins and USD. Rising OI with rising price usually means new longs; falling OI means positions are closing. Default: hourly for the last 24h.

Inputs: coin (required), since, until, interval.

hydromancer_prediction_marketsPrediction markets (HIP-4 outcomes)B
Read-only

Settled Hyperliquid prediction markets (HIP-4 outcomes) with their result and trading stats, searchable by text, underlying asset or category.

Inputs: limit, search, category, underlying.

hydromancer_price_historyPrice candles (OHLCV)A
Read-only

Price history as candles (open, high, low, close, volume) for any market. Intervals from 1 second to 1 month. Default: 1h candles for the last 24h. since/until accept Relative ("30m", "6h", "24h", "7d"), a date ("2026-10-01"), a date-time ("2026-10-01T12:00:00Z"), "now", or Unix ms.

Inputs: coin (required), since, until, interval.

hydromancer_raw_requestAdvanced: any Hydromancer API requestA
Read-only

Send any Hydromancer /info request directly, for endpoints the other tools do not cover (e.g. vaultSummaries, historicalOrders, spotMeta, outcomeMeta, delegations, perpDexStatus). Pass the request body as JSON including "type". Full list: https://docs.hydromancer.xyz/llms.txt . Read-only: this server never places orders.

Inputs: body (required), limit.

hydromancer_recent_liquidationsRecent liquidationsA
Read-only

Positions that were force-closed (liquidated), newest first, for one market or the whole exchange, with totals by side. "Long liquidated" means a long position was wiped out. Default window: last 24h.

Inputs: coin, limit, since, until.

hydromancer_top_tradersTop traders leaderboardA
Read-only

Rank Hyperliquid traders by realized profit, win rate or volume over 1 day to all time, with filters that remove bots and one-off wallets. Use for "who are the best traders this week?", "find consistent winners on stocks (dex xyz)" or "top traders using builder X". Pair with hydromancer_wallet_overview to see what they hold now.

Inputs: limit, market, offset, period, +5 more.

hydromancer_wallet_closed_tradesWallet closed trades (open-to-close round trips)A
Read-only

Completed trades for a wallet: each row is a full position from open to close with entry, exit, size, gross and net PnL, fees, funding and how long it was held. Best tool for judging trading skill ("what is this wallet's win rate and best coin?"). Default window: last 30 days. since/until accept Relative ("30m", "6h", "24h", "7d"), a date ("2026-10-01"), a date-time ("2026-10-01T12:00:00Z"), "now", or Unix ms.

Inputs: address (required), coin, limit, since, +1 more.

hydromancer_wallet_fundingWallet funding paymentsA
Read-only

Funding paid or received by a wallet's open positions, hour by hour, with totals per coin. Positive = received, negative = paid. Default window: last 7 days.

Inputs: address (required), since, until.

hydromancer_wallet_open_ordersWallet open orders (limits, stop-losses, take-profits)B
Read-only

All resting orders for a wallet right now, including stop-loss and take-profit triggers. Shows where a trader plans to buy, sell or exit.

Inputs: address (required).

hydromancer_wallet_overviewWallet overview: balance, open positions, PnL recordA
Read-only

One-call profile of any Hyperliquid wallet: account value, every open perp position (side, size, entry, liquidation price, leverage, unrealized PnL), spot balances and its realized trading record (PnL, win rate, trade count, volume, human score). Use this first for questions like "what is this wallet holding?" or "is this trader any good?". Set includeHip3=true to include HIP-3 markets such as xyz:TSLA.

Inputs: address (required), includeHip3.

hydromancer_wallet_tradesWallet trade history (fills)A
Read-only

Every fill (buy/sell execution) a wallet made in a time window, newest first, with totals: volume, realized PnL, fees and a per-coin breakdown. since/until accept Relative ("30m", "6h", "24h", "7d"), a date ("2026-10-01"), a date-time ("2026-10-01T12:00:00Z"), "now", or Unix ms. Default window: last 24h. Large orders split into many fills are merged by default.

Inputs: address (required), coin, limit, since, +3 more.

hydromancer_wallet_transfersWallet deposits, withdrawals, transfers and liquidationsA
Read-only

Money movements for a wallet: deposits, withdrawals, sends, spot/perp transfers, vault deposits and liquidations. Default window: last 30 days. since/until accept Relative ("30m", "6h", "24h", "7d"), a date ("2026-10-01"), a date-time ("2026-10-01T12:00:00Z"), "now", or Unix ms.

Inputs: address (required), limit, since, until.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools target clearly different resources or actions, such as wallet fills versus completed positions, market snapshots versus price history, and wallet funding versus market funding history. There is some overlap around wallet performance: wallet_overview, wallet_closed_trades, and top_traders can all answer questions about win rate or trader quality, and raw_request is a catch-all that overlaps every tool.

    Naming Consistency5/5

    All tools use a consistent hydromancer_ prefix with snake_case names. The set mixes descriptive noun phrases and verb-led names, but the convention is predictable and readable throughout.

    Tool Count4/5

    At 19 tools the server is on the heavy side, but the breadth matches a multi-domain Hyperliquid analytics surface covering wallets, markets, liquidations, builders, prediction markets, and usage. Each tool maps to a distinct data need, with no obviously redundant tools.

    Completeness4/5

    The surface covers the core read-only analytics workflow very well: wallet profiling, trades, positions, orders, transfers, market data, history, depth, rankings, and liquidations. Some Hyperliquid endpoints such as active prediction markets, spot metadata, historical orders, and vault details are only reachable through raw_request, so coverage is broad but not fully first-class.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform cryptocurrency trading analysis and execution with 38+ tools including real-time market data, technical indicators, risk management, and support for both paper trading and live execution on Hyperliquid.
      7
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides comprehensive crypto intelligence for the Hyperliquid exchange, allowing users to query trader profiles, behavioral cohorts, and live market data. It enables AI agents to analyze over 1.8 billion trades, track whale positions, and access real-time liquidation heatmaps.
      106
      59 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely trade on Hyperliquid perpetual exchange, including order placement, position management, market data retrieval, and vault operations via natural language.
      29 PyPI
      24
      MIT