Skip to main content
Glama
hydromancer-mcp

hydromancer-mcp

by joshavenue

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 /info endpoints

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

  • Read-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 httpx and pydantic; Python 3.10+

Hosts contacted

The server makes HTTPS requests to one of these hosts:

Host

When

api.hydromancer.xyz

Every tool call (default)

api-testnet.hydromancer.xyz

Instead of the above, only if you set HYDROMANCER_BASE_URL to the testnet URL

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

Cursor

~/.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 --help

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

hydromancer_wallet_overview

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)

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_top_traders

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

hydromancer_market_snapshot

Price, 24h volume, open interest; max leverage in the top-markets list

hydromancer_price_history

Candles from 1 second to 1 month

hydromancer_funding_history

Funding rates, average and annualized

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 and HIP-3 exchange, searchable by name or category

hydromancer_my_usage

Your own API usage

hydromancer_raw_request

Any other Hydromancer /info request, e.g. open orders, transfers, vaults (endpoint list)

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

Set to https://api-testnet.hydromancer.xyz/info for testnet; any other host is refused

HYDROMANCER_TIMEOUT_MS

30000

Request timeout

HYDROMANCER_MAX_RESULT_CHARS

40000

Cap on one tool result (minimum 1000), so the AI is not flooded

Security

  • Read-only. Every request goes to the /info endpoint, 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 Authorization header 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_request results 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-After header 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 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.

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

License

MIT © Hydromancer BV

Available Tools

12 tools
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_snapshotMarket snapshot: price, 24h volume, open interestA
Read-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 usageA
Read-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)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, 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 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. 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 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.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation4/5

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

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
      A
      quality
      C
      maintenance
      Read-only Hyperliquid and cross-exchange market research for AI agents, providing structured tools for live market data without requiring authentication.
      9
      81 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      12
      85 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT