io.github.ironflowshPublished by GitHub account ironflowshv0.11.1Updated Oct 30, 2026
Read-only Hyperliquid data for AI agents: fills, candles, funding, liquidations, wallet analytics.
Read-only Hyperliquid market data and wallet analytics for AI assistants: trades, candles, funding, liquidations and trader profiles.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.ironflowsh%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"ironflowsh": {
"type": "http",
"url": "https://mcp.ironflow.sh/mcp"
}
}
}MCP server for Ironflow: Hyperliquid market data, wallet analytics and liquidation alerts for Claude, Cursor and any MCP client. It covers native perps, HIP-3 builder markets, HIP-4 outcome markets and spot. 45 tools: 41 read data, including run_query for read-only SQL over every Hyperliquid fill, wallet, funding and liquidation table, and 4 set up liquidation alerts that Ironflow posts to your Discord, Slack, Telegram or webhook.
No API key needed to start: keyless calls get 30 requests per minute, 2,000 per day and 24 hours of history. A free key from ironflow.sh/key raises that to 60 requests per minute and 30 days. Agents with a USDC wallet on Base can also pay per call with x402, from $0.001 and with no key (pay per call).
The hosted server needs no install and no key: https://mcp.ironflow.sh/mcp (Streamable HTTP).
[Add to Cursor] [Install in VS Code]
Claude Code
Claude (claude.ai and Claude Desktop): open Customize → Connectors, click Add custom connector, enter the name Ironflow and the URL https://mcp.ironflow.sh/mcp, then click Add. On Team and Enterprise plans an Owner adds it under Organization settings → Connectors → Add → Custom, and members then click Connect.
Cursor: the button above, or add this to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):
VS Code: the button above, or
Local server (stdio): npx -y @ironflowsh/mcp, see Local server.
Send it as Authorization: Bearer if_your_api_key, or as ?key=if_your_api_key on the URL for clients that cannot set headers.
In Cursor, add "headers": { "Authorization": "Bearer if_your_api_key" } next to url.
Requires Node.js 18+. Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%/Claude/claude_desktop_config.json on Windows):
The env block is optional. Claude Code: claude mcp add ironflow -- npx -y @ironflowsh/mcp.
To host the HTTP server yourself: npx -y -p @ironflowsh/mcp ironflow-mcp-http (listens on PORT, default 8080, path /mcp).
Ask anything (SQL): describe_data lists the queryable tables, columns and example queries; run_query runs one read-only ClickHouse SELECT over them (every fill, per-wallet daily totals, behaviour labels, funding, mark and oracle prices, open interest, liquidations, builder-code fills, transfers, vault flows); get_wallet_behavior returns 30-day trading-style labels per wallet. Keyless queries see the last 24 hours; a free key sees 30 days.
Market data: get_price, get_recent_trades, get_candles, get_funding_rates, get_open_interest, get_open_interest_changes, get_premium, get_outcome_markets, get_liquidations, get_liquidation_summary, get_auto_deleveraging, get_fills, get_mark_prices, get_vault_operations, list_markets, get_markets_snapshot
Market analytics: get_funding_stats, get_pnl_leaderboard, get_market_top_wallets, get_wallet_labels, get_vault_leaderboard and get_liquidation_levels (needs a free API key)
Signals: get_top_traders, get_market_leaders, get_early_movers, get_trader_profile
Wallet analytics: get_user_state, get_positions_at, get_user_summary, get_user_pnl_series, get_user_funding, get_user_maker_taker, get_user_ledger
Cohorts: list_cohorts, get_cohort_addresses
Status: get_status, get_status_metrics, get_status_history
Liquidation alerts (need an API key; a free key allows one): create_liquidation_alert has Ironflow post matching liquidations to a Discord channel, Slack channel, Telegram chat or HTTPS webhook within seconds, filtered by market, side, size and wallet, and keeps posting after the conversation ends; list_liquidation_alerts, test_liquidation_alert and delete_liquidation_alert manage them. Guide: docs.ironflow.sh/guides/liquidation-alerts.
Markets can be given as display symbols (BTC-PERP, xyz:NVDA-PERP, HYPE/USDC) or Hyperliquid names (BTC, @107, xyz:NVDA), and times as Unix ms, Unix seconds, ISO 8601 or relative to now (-7d, -24h, now). When the API reads a name, or serves a window that starts later than asked because of the key's history limit, the result starts with a notice saying so. Fill history covers a rolling 12 months. There is no order book, order status or streaming tool; for live feeds the REST API has /v1/liquidations/stream and /v1/trades/stream (Server-Sent Events).
Each API call carries two headers so we can see which apps and tools people use: X-Ironflow-Client (the MCP client's name and version, e.g. claude-code/2.1.0) and X-Ironflow-Tool (the tool name). The hosted server logs each request's method, tool arguments, client name, status, whether the tool returned an error, the API status and error code behind it, and a salted hash of the caller's IP. It never logs IPs or API keys.
MIT
Source: README.md at commit 35da768
Describe SQL tables
Returns the SQL tables of Ironflow's Hyperliquid data (every fill, per-wallet daily totals, wallet behaviour labels, funding, mark and oracle prices, open interest, liquidations, builder-code fills, transfers, vault flows), their columns, how far back each goes, query tips, worked examples and your own limits.
Takes no parameters.
Run SQL query
Run one read-only ClickHouse SELECT over Ironflow's Hyperliquid tables (hl.fills, hl.wallet_daily, hl.wallet_behavior, hl.funding, hl.mark_prices, hl.oracle_prices, hl.open_interest, hl.liquidations, hl.builder_fills, hl.transfers, hl.vault_operations). Aggregate in SQL: results are capped (1,000 rows keyless). Keyless: last 24 hours, 5 s per query, 60 query seconds per hour per IP; a free key from https://ironflow.sh/key gives 30 days of history.
sqlrequiredmax_rowsWallet behavior labels
How Hyperliquid wallets trade, from their last 30 days: labels (market_maker, high_frequency, whale, directional, consistent_winner, big_loser, revenge_sizing, often_liquidated, hip3_trader, spot_trader, prediction_trader) and the numbers behind them (maker share, buy/sell imbalance, fills per day, green-day share, profit factor, liquidations). Look up specific addresses, or list wallets with one label.
labellimitsort_byaddressesmin_volume_usdMarket price
Latest mark price of a Hyperliquid market: native perps, HIP-3 builder perps (e.g. xyz:NVDA-PERP) and spot.
marketrequiredRecent trades
Latest tick-level trades on a Hyperliquid market from our own nodes: price, size, side and block time. Covers native perps, HIP-3 builder markets, HIP-4 outcomes and spot.
limitmarketrequiredCandles (OHLCV)
OHLCV candles for a Hyperliquid market, computed from tick-level trades.
limitmarketrequiredintervalFunding rate history
Hourly funding rate history for a Hyperliquid perp, including HIP-3 builder perps. A positive rate means longs pay shorts.
limitmarketrequiredOpen interest
Latest open interest of a Hyperliquid perp, in base units, with its 24h volume in USD.
marketrequiredLiquidations
Liquidations on a Hyperliquid perp, read from our own nodes: price, size, side and the liquidated wallet. Hyperliquid's public API has no liquidation feed.
limitmarketrequiredLiquidation summary
Liquidations across every Hyperliquid market (or one market) over the last N minutes, totalled: count, notional, longs vs shorts liquidated, the top markets and the largest single liquidation. Use it for 'who got liquidated in the last hour?'. Keyless calls can look back 60 minutes, keyed calls up to 240.
marketminutesWallet fills
Every fill for one Hyperliquid wallet, optionally for one market, from indexed history: price, size, side, fee and realized PnL. Hyperliquid's own userFills endpoints stop at the 10,000 most recent fills.
limitmarketaddressrequiredMark and oracle price
Latest mark price, oracle price and hourly funding rate of a Hyperliquid perp.
marketrequiredVault deposits and withdrawals
Deposits into and withdrawals from one Hyperliquid vault or one depositor. Pass vault, address, or both; at least one is required (HLP is 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303).
limitvaultaddressLiquidation levels
Liquidated notional on a Hyperliquid perp bucketed by price: where longs and shorts were wiped out. Needs a Builder or Enterprise key; keyless and free-key calls return 403.
marketrequiredbucket_sizeVault leaderboard
Hyperliquid vaults ranked by net deposits (deposits minus withdrawals) over the last 7 days, with depositor counts. Keyless calls see the last 24 hours; a free key from https://ironflow.sh/key gives the full 7 days.
limitFunding statistics
Funding statistics per time bucket for a Hyperliquid perp: average, minimum, maximum and annualized rate.
limitmarketrequiredintervalWallet positions
Open positions and unrealized PnL for a Hyperliquid wallet right now, across native and HIP-3 perps. Use it for questions like 'is this wallet long or short?'
addressrequiredWallet funding payments
Funding a Hyperliquid wallet paid or received, per market per bucket. Positive means received, negative means paid. bucket=1d gives daily totals, 1h the raw hourly payments.
tofromlimitbucketmarketaddressrequiredWallet maker/taker split
Maker vs taker breakdown of a Hyperliquid wallet's fills per market: volume, fees and rebates. A high maker share with negative maker fees marks a market maker.
tofrommarketaddressrequiredWallet ledger
Vault deposits, withdrawals and transfers for a Hyperliquid wallet. Positive amounts go into the account. Account deposits and withdrawals are recorded only up to 2026-06-06.
tofromlimitaddressrequiredevent_typesPnL leaderboard
Every Hyperliquid wallet ranked by realized PnL, biggest losses or volume over a window. Wallets with fewer than 5 fills in the window are left out.
tofromlimitsort_byTop wallets in a market
Top wallets on one Hyperliquid market by volume or realized PnL, up to 200 rows.
tofromlimitmarketrequiredsort_byMarkets snapshot
Active Hyperliquid markets ranked in one call: mark price, 24h change, 24h volume, open interest and current hourly funding. Sort by abs_funding for the most extreme funding, abs_change_24h for the biggest movers, or volume (default). Use min_volume_usd to skip illiquid markets. Returns the top 25 unless limit is set.
limitorderissuersort_bymarket_classmin_volume_usdWallet summary
One Hyperliquid wallet's stats over a window: volume, realized PnL, fill count, win rate, maker share and markets traded.
tofromaddressrequiredWallet labels
Labels for notable Hyperliquid wallets: top whales by 24h volume, top traders by 30-day realized PnL, vaults and vault leaders. Pass addresses to check specific wallets; without them it lists the whales and smart money.
addressessmart_top_nwhale_top_nWallet PnL curve
Realized PnL curve of a Hyperliquid wallet over time, bucketed (for example hourly or daily).
tofromaddressrequiredbucket_msTop traders
Hyperliquid traders ranked across all markets by results over 7, 30 or 90 days: win rate, profit factor, realized PnL, max drawdown and best markets. sort=top ranks by realized PnL, lowrisk by smallest max drawdown, new by most recently first seen.
sortlimitwindowMarket leaders
The best traders on one Hyperliquid market, ranked by profit factor then win rate, among wallets with at least 5 closed trades there.
limitmarketrequiredwindowEarly movers
Wallets whose large orders (at least $10k) on a Hyperliquid market were followed by a price move in their direction within 30 minutes. Returns a lead score in basis points and a hit rate per wallet. Past activity does not predict future results.
limitmarketrequiredwindowTrader profile
A Hyperliquid wallet's trading record over 7, 30 or 90 days: win rate, profit factor, realized PnL, max drawdown and its best markets.
windowaddressrequiredList cohorts
List available address cohorts: six predefined groups (top_pnl_30d, high_volume_30d, whale_fills, net_withdrawers_7d, liquidation_prone, vault_whales) plus any custom cohorts the caller has created
Takes no parameters.
Cohort addresses
Wallet addresses in one named wallet cohort.
namerequiredAPI status
Ironflow service status right now: overall state, data freshness per venue and component health.
Takes no parameters.
API performance metrics
Ironflow performance over rolling windows: API latency and error rate, ingestion lag and synthetic probe timings.
Takes no parameters.
API uptime history
Ironflow uptime and data freshness per hour over the last 24 hours (default) or 7 days.
periodList markets
Find how a Hyperliquid market is named: perps (native and HIP-3), spot and live HIP-4 outcomes, with symbol, class, issuer, base asset and Hyperliquid coin. Search with q (q=nvda finds xyz:NVDA-PERP and the other NVDA perps). Pages of up to 100 rows; pass pagination.next_cursor as cursor for the next page.
qlimitcursorissuersourcemarket_classinclude_inactive100% 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.
claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp{ "mcpServers": { "ironflow": { "url": "https://mcp.ironflow.sh/mcp" } }}code --add-mcp '{"name":"ironflow","type":"http","url":"https://mcp.ironflow.sh/mcp"}'claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp \ --header "Authorization: Bearer if_your_api_key"npx -y @ironflowsh/mcp{ "mcpServers": { "ironflow": { "command": "npx", "args": ["-y", "@ironflowsh/mcp"], "env": { "IRONFLOW_API_KEY": "if_your_api_key" } } }}