Hydromancer

Read-only Hyperliquid data: wallets, top traders, markets, funding and liquidations.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package hydromancer-mcp

Claude Code

claude mcp add hydromancer -e 'HYDROMANCER_API_KEY=<your hydromancer_api_key>' -- npx -y hydromancer-mcp@0.2.1

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "hydromancer": {
            "command": "npx",
            "args": [
                "-y",
                "hydromancer-mcp@0.2.1"
            ],
            "env": {
                "HYDROMANCER_API_KEY": "<your hydromancer_api_key>"
            }
        }
    }
}

Environment variables

HYDROMANCER_API_KEY required secret Your Hydromancer API key: https://docs.hydromancer.xyz/readme/get-api-keys

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

Hydromancer MCP
1. Get a Hydromancer API key
2. Add it to your AI app
3. Ask
Tools
Settings
Good to know
Development
From the Hydromancer blog
License

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.

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

Frequently asked questions

What is Hydromancer?

Read-only Hyperliquid data: wallets, top traders, markets, funding and liquidations.

How do I install Hydromancer?

It runs on your machine. In Claude Code: claude mcp add hydromancer -e 'HYDROMANCER_API_KEY=<your hydromancer_api_key>' -- npx -y hydromancer-mcp@0.2.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Hydromancer need an API key?

Yes. It expects HYDROMANCER_API_KEY, which you set in its configuration.

Is Hydromancer open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Hydromancer?

It is published by joshavenue. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: joshavenue
Category: Finance and payments
Runs: Local
GitHub stars: ★ 0
License: MIT
Language: TypeScript
Last commit: Oct 31, 2026
Open issues: 0
Version: 0.2.1
Published: Oct 31, 2026

io.github.joshavenue/hydromancer-mcp

Similar servers

True Value Rankings Cryptocurrency fundamentals for agents: TVR Scores, rankings and model-derived valuatio...
TILLA - market data on one clock Crypto, US stocks, FX, rates, macro and Bitcoin node data on one clock, for any AI agent.
Presso Events Run ticketed events from your AI assistant: create events, sell tickets via Stripe, che...
ABRA Flexi MCP by usefulapi MCP server for ABRA Flexi — accounting, contacts, stock and draft-checked invoice creat...
earnrate Picks the credit card in your wallet that earns the most at a merchant, and says why.
Mekari Jurnal MCP by usefulapi MCP server for Mekari Jurnal — company accounting, sales, purchases and customer/vendor...
GDEX Trading GDEX (gdex.pro) trading for AI agents: spot, perps and HyperLiquid on Solana, EVM and m...
SkuVault MCP by usefulapi MCP server for SkuVault — products, inventory, sales, purchase orders and stock adjustm...

Finance and payments