Hydromancer

io.github.joshavenuePublished by GitHub account joshavenuev0.2.1Updated Nov 7, 2026

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

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Read-only Hyperliquid market and wallet data via the Hydromancer API, letting an assistant inspect positions, traders, markets, funding and liquidations.

What you can do
  • Inspect wallets: overview, positions, fills, closed trades, open orders, transfers and funding
  • Compare up to 1,000 wallets at once and rank top traders with bot filters
  • Read market data: snapshots, candles, funding rates, open interest, liquidations, depth and slippage
  • List markets and HIP-3 exchanges, settled prediction markets, and builder app activity
  • Send arbitrary Hydromancer info requests and check your own API usage
When to use it
Useful when you want an assistant to answer plain-language questions about Hyperliquid trading activity — evaluating a wallet's skill, finding consistent top traders, checking funding or open-interest trends, or estimating slippage for a trade size — without writing API code.
Requirements
Runs locally over stdio via npx (Node.js 20 or newer). Requires a Hydromancer API key in the HYDROMANCER_API_KEY environment variable. Optional settings cover base URL (mainnet or testnet hosts only), timeout and result size cap. Network access to the Hydromancer API is needed.
Before you install
Each tool call consumes tokens from your Hydromancer plan, so usage has a cost; check it with the usage tool. The API key is read from app settings and sent to the Hydromancer API host. The server is read-only and cannot place, cancel or sign orders, and it does not handle funds or private keys. Wallet addresses you query are sent to Hydromancer.

Installation

In SourceWeft

  1. Open Hydromancer in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

json
{  "mcpServers": {    "hydromancer": {      "command": "npx",      "args": ["-y", "hydromancer-mcp"],      "env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }    }  }}

Restart Claude Desktop.

Claude Code

bash
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:

toml
[mcp_servers.hydromancer]command = "npx"args = ["-y", "hydromancer-mcp"]env = { HYDROMANCER_API_KEY = "YOUR_KEY" }

VS Code (GitHub Copilot)

.vscode/mcp.json:

json
{  "servers": {    "hydromancer": {      "command": "npx",      "args": ["-y", "hydromancer-mcp"],      "env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }    }  }}

From a local copy

bash
git clone https://github.com/joshavenue/Hydromancer-MCP && cd Hydromancer-MCPnpm 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

ToolWhat it answers
hydromancer_wallet_overviewBalance (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_walletsUp to 1,000 wallets at once, with balance and account mode, sorted by balance
hydromancer_wallet_tradesFills in a time window, with volume, PnL, fees and per-coin totals
hydromancer_wallet_closed_tradesRound-trip trades: win rate, net PnL, hold time, best coin
hydromancer_wallet_open_ordersResting limits, stop-losses, take-profits
hydromancer_wallet_transfersDeposits, withdrawals, sends, vault moves, liquidations
hydromancer_wallet_fundingFunding paid or received, per coin
hydromancer_top_tradersLeaderboard by profit, win rate or volume, with bot and activity filters
hydromancer_market_snapshotPrice, 24h volume and open interest (max leverage in the top-markets list)
hydromancer_price_historyCandles from 1 second to 1 month (including 15s and 30s)
hydromancer_funding_historyFunding rates, average and annualized
hydromancer_open_interest_historyOpen interest trend, 1 minute to 1 month buckets
hydromancer_recent_liquidationsLiquidations by market, with long/short totals
hydromancer_market_depthOrder book depth and slippage for a trade size
hydromancer_list_marketsEvery market, HIP-3 exchanges, search by name or category
hydromancer_builder_activityVolume, users and fees for a builder app
hydromancer_prediction_marketsSettled HIP-4 prediction markets
hydromancer_my_usageYour own API usage and tokens
hydromancer_raw_requestAny 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

VariableDefaultPurpose
HYDROMANCER_API_KEY(required)Your API key
HYDROMANCER_BASE_URLhttps://api.hydromancer.xyz/infoAPI endpoint. Only the mainnet and testnet Hydromancer hosts are accepted.
HYDROMANCER_TIMEOUT_MS30000Request timeout
HYDROMANCER_MAX_RESULT_CHARS40000Cap 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

bash
npm installnpm run buildnpm test                                   # offline unit testsHYDROMANCER_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

Source: README.md at commit 4dbf08b

Tools

19

hydromancer_wallet_overview

Wallet overview: balance, open positions, PnL record

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.

ParametersaddressrequiredincludeHip3

hydromancer_compare_wallets

Compare many wallets at once

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

ParametersaddressesrequiredincludeHip3minBalanceUsd

hydromancer_wallet_trades

Wallet trade history (fills)

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.

ParameterscoinlimitsinceuntiloffsetaddressrequiredmergeSplitOrders

hydromancer_wallet_closed_trades

Wallet closed trades (open-to-close round trips)

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.

Parameterscoinlimitsinceuntiladdressrequired

hydromancer_wallet_open_orders

Wallet open orders (limits, stop-losses, take-profits)

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.

Parametersaddressrequired

hydromancer_wallet_transfers

Wallet deposits, withdrawals, transfers and liquidations

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.

Parameterslimitsinceuntiladdressrequired

hydromancer_wallet_funding

Wallet funding payments

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.

Parameterssinceuntiladdressrequired

hydromancer_top_traders

Top traders leaderboard

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.

ParameterslimitmarketoffsetperiodrankBybuilderminTradesexcludeBotsminDaysActive

hydromancer_market_snapshot

Live price, volume and open interest for markets

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

Parameterstopcoins

hydromancer_price_history

Price candles (OHLCV)

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.

Parameterscoinrequiredsinceuntilinterval

hydromancer_funding_history

Funding rate history for a market

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.

Parameterscoinrequiredsinceuntil

hydromancer_open_interest_history

Open interest history

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.

Parameterscoinrequiredsinceuntilinterval

hydromancer_recent_liquidations

Recent liquidations

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.

Parameterscoinlimitsinceuntil

hydromancer_market_depth

Order book depth and slippage

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.

ParameterscoinrequiredsinceorderSizeUsd

hydromancer_list_markets

List every market and HIP-3 exchange

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.

Parameterslimitsearchcategory

hydromancer_builder_activity

Builder app activity (trades routed through an app)

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.

Parameterslimitsinceuntilbuilderrequired

hydromancer_prediction_markets

Prediction markets (HIP-4 outcomes)

Settled Hyperliquid prediction markets (HIP-4 outcomes) with their result and trading stats, searchable by text, underlying asset or category.

Parameterslimitsearchcategoryunderlying

hydromancer_my_usage

My Hydromancer API usage

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.

Parametersdays

hydromancer_raw_request

Advanced: any Hydromancer API request

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.

Parametersbodyrequiredlimit

Version history

1
  1. v0.2.1LatestOct 31, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts