Hydromancer

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:

• How to Query Reservoir's Hyperliquid Data
• Hyperliquid vs Hydromancer API: When to Upgrade?
• How to View Entire Trader Positioning on Hyperliquid
• How to Find a Reliable Peer for Your Hyperliquid Node
• Hyperliquid Builder Codes: How They Work and How to Track Fees
• Hyperliquid Testnet Guide: Faucets, API URLs and Mainnet Gotchas
• Hyperliquid Fees and Revenue: A Guide for Builders
• HyperCore vs HyperEVM: Is Hyperliquid an L1 or L2?
• Hyperliquid Tick Size and Lot Size: Round Prices and Sizes
• How to Build a Hyperliquid Orderbook Heatmap
• Hyperliquid Vaults API: Track Performance and Depositors
• How to Get a Hyperliquid Wallet's Trade History (API + Bulk)
• Hyperliquid Funding Rates: How They Work and its History
• How to Build a Hyperliquid Copy Trading Bot
• How to Build a Hyperliquid Trading Bot
• Hyperliquid Leaderboard: How to Track Top Addresses' PnL
• How to Read Hydromancer's Live Stats Page
• Hyperliquid Rate Limits: What is it & Solution
• Top HIP-3 Market Deployers by the Numbers
• Hyperliquid API Guide: Endpoints, API Keys, Limits and Python Examples
• Top Prop Firms on Hyperliquid: Side-by-Side Comparison
• How to Build with Liquidation Data from Hyperliquid
• How to Build a Hyperliquid Whale Tracker (Live Positions, Fills and Alerts)

License

MIT