Hydromancer MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Hydromancer MCP Who got liquidated on Hyperliquid in the last 6 hours, longs or shorts?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 like24h,7dor2026-10-01Safe: 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(orapi-testnet.hydromancer.xyzif 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-mcpCursor
~/.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 buildThen 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 |
| Balance (correct for unified-account and portfolio-margin wallets), account mode, open positions (entry, liquidation price, leverage, PnL), spot balances, trading record, bot score |
| Up to 1,000 wallets at once, with balance and account mode, sorted by balance |
| Fills in a time window, with volume, PnL, fees and per-coin totals |
| Round-trip trades: win rate, net PnL, hold time, best coin |
| Resting limits, stop-losses, take-profits |
| Deposits, withdrawals, sends, vault moves, liquidations |
| Funding paid or received, per coin |
| Leaderboard by profit, win rate or volume, with bot and activity filters |
| Price, 24h volume and open interest (max leverage in the top-markets list) |
| Candles from 1 second to 1 month (including 15s and 30s) |
| Funding rates, average and annualized |
| Open interest trend, 1 minute to 1 month buckets |
| Liquidations by market, with long/short totals |
| Order book depth and slippage for a trade size |
| Every market, HIP-3 exchanges, search by name or category |
| Volume, users and fees for a builder app |
| Settled HIP-4 prediction markets |
| Your own API usage and tokens |
| Any other Hydromancer |
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 |
| (required) | Your API key |
|
| API endpoint. Only the mainnet and testnet Hydromancer hosts are accepted. |
|
| Request timeout |
|
| 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
balanceUsduses 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 APIFrom the Hydromancer blog
Guides and research on getting and using Hyperliquid data:
Hyperliquid Builder Codes: How They Work and How to Track Fees
Hyperliquid Testnet Guide: Faucets, API URLs and Mainnet Gotchas
How to Get a Hyperliquid Wallet's Trade History (API + Bulk)
Hyperliquid API Guide: Endpoints, API Keys, Limits and Python Examples
How to Build a Hyperliquid Whale Tracker (Live Positions, Fills and Alerts)
License
MIT
Available Tools
19 toolshydromancer_builder_activityBuilder app activity (trades routed through an app)ARead-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 onceARead-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 marketARead-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 exchangeARead-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 slippageARead-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 marketsARead-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 usageARead-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 historyARead-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)BRead-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)ARead-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 requestARead-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 liquidationsARead-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 leaderboardARead-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)ARead-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 paymentsARead-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)BRead-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 recordARead-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)ARead-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 liquidationsARead-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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Hyperliquid market data, wallet analytics and liquidation alerts for AI agents.
Build, backtest and paper-run Hyperliquid strategies from your AI assistant.
Read-only Hyperliquid analytics: orderflow, liquidation levels, whale positioning, funding.
Hyperliquid - 2 tools for perpetuals, options, and position data
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.7MIT

Coinversaa Pulseofficial
AlicenseAqualityBmaintenanceProvides 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.10659 npm10MIT- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely trade on Hyperliquid perpetual exchange, including order placement, position management, market data retrieval, and vault operations via natural language.29 PyPI24MIT
- AlicenseBqualityDmaintenanceIntegrates with Hyperliquid DEX to enable trading, account management, and market data queries through natural language.123MIT