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?"
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
Read-only MCP server for the Hydromancer Hyperliquid API, in Python. Ask your AI app about wallets, top traders, markets, funding and liquidations in plain English.
Disclosure: this package is maintained by the Hydromancer team. You need a Hydromancer API key to use it.
uvx hydromancer-mcp
"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%?"
12 read-only tools: wallets, trades, top traders, markets, funding, depth, liquidations, your API usage, plus a raw request tool for other
/infoendpointsFriendly inputs: coin names in any case (
btc,$ETH,ETH-PERP,xyz:tsla), times like24h,7dor2026-10-01Read-only: it cannot place, cancel or sign orders, and it never handles funds or private keys
Few dependencies: besides the MCP SDK it uses only
httpxandpydantic; Python 3.10+
Hosts contacted
The server makes HTTPS requests to one of these hosts:
Host | When |
| Every tool call (default) |
| Instead of the above, only if you set |
Any other HYDROMANCER_BASE_URL is refused at startup, so your key cannot be sent elsewhere. Redirects are not followed. No telemetry. (Installing with uvx or pip downloads the package from PyPI; the server itself never contacts PyPI.)
Related MCP server: market-depth-lab-mcp
1. Get a Hydromancer API key
See Get API keys.
2. Add it to your AI app
You need uv (for uvx). Replace YOUR_KEY with your key.
Claude Desktop
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"hydromancer": {
"command": "uvx",
"args": ["hydromancer-mcp"],
"env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }
}
}
}Restart Claude Desktop. If it cannot find uvx, use the full path from which uvx as the command.
Claude Code
claude mcp add hydromancer -e HYDROMANCER_API_KEY=YOUR_KEY -- uvx hydromancer-mcpCursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"hydromancer": {
"command": "uvx",
"args": ["hydromancer-mcp"],
"env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }
}
}
}Codex
~/.codex/config.toml:
[mcp_servers.hydromancer]
command = "uvx"
args = ["hydromancer-mcp"]
env = { HYDROMANCER_API_KEY = "YOUR_KEY" }Other MCP apps, or pip
Any app that runs stdio MCP servers works with uvx hydromancer-mcp. Without uv:
pip install hydromancer-mcp
hydromancer-mcp --help3. Ask
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.Who got liquidated on Hyperliquid in the last 6 hours? Longs or shorts?BTC, ETH and HYPE: price, 24h volume and open interest.What's the BTC funding rate averaged over the last week, annualized?How deep is the xyz:TSLA order book within 1% of the price?
Tools
Tool | What it answers |
| Balance (handles unified-account and portfolio-margin wallets), open positions with entry, liquidation price, leverage and PnL, spot balances, trading record, human score (low suggests a bot) |
| Fills in a time window, with volume, PnL, fees and per-coin totals |
| Round-trip trades: win rate, net PnL, hold time, best coin |
| Leaderboard by profit, win rate or volume, with bot and activity filters |
| Price, 24h volume, open interest; max leverage in the top-markets list |
| Candles from 1 second to 1 month |
| Funding rates, average and annualized |
| Liquidations by market, with long/short totals |
| Order book depth and slippage for a trade size |
| Every market and HIP-3 exchange, searchable by name or category |
| Your own API usage |
| 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 |
|
| Set to |
|
| Request timeout |
|
| Cap on one tool result (minimum 1000), so the AI is not flooded |
Security
Read-only. Every request goes to the
/infoendpoint, which only returns data.What is sent. Only the requests needed for each tool call (the wallet addresses, coin names and time ranges you ask about, plus a market-list lookup to resolve coin names), your key, and a User-Agent naming this package and its version, to the hosts above.
Your key stays local. It is read from the environment, sent only in the
Authorizationheader to the hosts above, never logged or printed, and replaced with***if it ever appears in an error message.Responses are data, not instructions. API responses (market names, descriptions, any text field) are returned to the AI as data. The server tells the AI to treat them as data and never to follow instructions found inside them, and
hydromancer_raw_requestresults carry the same note. This is guidance to the AI, not a guarantee, so review what your AI app does with the results.Rate limits. On HTTP 429 the server retries at most twice, waiting as long as the API asks (the
Retry-Afterheader or the response body, otherwise 1 s then 2 s, plus a fraction of a second), but only if that wait is 10 seconds or less. Otherwise it tells the AI how long to wait.Size limits. Responses over 64 MB are refused, and each tool result is capped (see
HYDROMANCER_MAX_RESULT_CHARS) with a note when it is cut.
Good to know
The data is for information only and is not financial advice.
Each tool call makes one or more ordinary API requests (some tools combine several, and coin names are checked against the market list), and each request counts toward your key's usage. Check it with
hydromancer_my_usage.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.
Binary snapshot endpoints are not supported.
Development
uv sync
uv run pytest # offline unit tests (HTTP mocked with respx)
HYDROMANCER_LIVE=1 HYDROMANCER_API_KEY=... uv run pytest -m live # opt-in live tests
HYDROMANCER_API_KEY=... uv run python scripts/smoke_stdio.py # real stdio round tripLicense
MIT © Hydromancer BV
Available Tools
12 toolshydromancer_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_snapshotMarket snapshot: price, 24h volume, open interestARead-only
Current mark/oracle/mid price, 24h volume and open interest (in coins and USD) for one or more markets. Leave coins empty for the top native markets by 24h volume, which also shows max leverage. 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, response times and tokens consumed.
Inputs: days.
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, userFunding, openInterestHistory). Pass the request body as JSON including "type". Full list: https://docs.hydromancer.xyz/llms.txt. Read-only: /info cannot place orders. Binary snapshot endpoints are not supported.
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. The summary covers all trades returned for the window (up to 500); rows are newest first. 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_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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools map cleanly to one resource+action (wallet overview, fills, closed positions, snapshot, candles, funding, liquidations, depth, market list). The one soft overlap is between wallet_overview and wallet_closed_trades, both pitched as ways to judge trading skill/win rate, but the descriptions explicitly steer usage ("Use this first", "Best tool for judging trading skill").
Every tool uses the same hydromancer_ prefix plus snake_case noun/verb structure (wallet_overview, market_snapshot, price_history, recent_liquidations). No camelCase or verb-style mixing anywhere in the set.
Twelve tools is well within a comfortable range for a data/analytics server. Each tool covers a distinct slice of the Hyperliquid surface (wallets, traders, markets, funding, liquidations, depth, usage) with no filler entries.
Wallet analytics, market data, leaderboards and usage are covered end-to-end for a read-only analytics domain. A few gaps exist (vault summaries, spot metadata, historical open interest), but hydromancer_raw_request acts as an explicit escape hatch so agents aren't blocked.
Maintenance
Related MCP Connectors
Hyperliquid market data, wallet analytics and liquidation alerts for AI agents.
Read-only Hyperliquid analytics: orderflow, liquidation levels, whale positioning, funding.
Read-only crypto market data: Hyperliquid liquidation heatmaps, liquidations, whales, funding, flow.
Read-only Hyperliquid wallet, market and portfolio research with source timestamps and coverage.
Related MCP Servers
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- AlicenseAqualityCmaintenanceRead-only Hyperliquid and cross-exchange market research for AI agents, providing structured tools for live market data without requiring authentication.981 npmMIT
- AlicenseAqualityBmaintenanceProvides AI agents read-only, keyless access to Hyperliquid market data, funding rates, account risk, and HyperEVM token transfers through MCP tools, with caching and rate limiting to protect upstream APIs.1285 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to read live Hyperliquid market data — perp and spot metadata, mid prices, order books, OHLCV candles, funding rates and history, and current open interest — keylessly from the exchange's public info API, with no wallet or trading access.105 npmMIT