Hyperliquid MCP server for AI agents

Ironflow runs a hosted MCP (Model Context Protocol) server at https://mcp.ironflow.sh/mcp. Connect Claude, Cursor or any MCP client by URL: nothing to install and no key needed to start.

MCP Server

The hosted server and the @ironflowsh/mcp package expose the same tools, grouped by capability:

Ask anything (SQL)

Tool	Description
`describe_data`	The SQL tables you can query, their columns, how far back each goes, tips, worked examples and your limits
`run_query`	One read-only ClickHouse SELECT over the `hl.*` tables (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`	30-day trading style per wallet: labels such as market_maker, directional, consistent_winner, revenge_sizing, and the numbers behind them

The agent reads describe_data, writes SQL, and runs it. Limits follow your tier: keyless calls see the last 24 hours with 5 seconds per query and 60 query seconds per hour per IP; a free key sees 30 days. The same thing over REST is POST /v1/query with {"sql": "..."}.

Market data

Tool	Description
`get_price`	Latest mark price for a market
`get_recent_trades`	Last N trades with price, size, and side
`get_candles`	OHLCV candlestick data
`get_funding_rates`	Funding rate history
`get_open_interest`	Open interest snapshots
`get_mark_prices`	Mark-price snapshots per market
`get_liquidations`	Liquidations with price, size, side and the liquidated wallet
`get_liquidation_summary`	Liquidations across all markets over the last N minutes, totalled
`list_markets`	Active markets in the registry, filterable by source / class / issuer

Historical queries

Tool	Description
`get_fills`	Historical fill events, filterable by wallet address
`get_vault_operations`	Vault deposit/withdraw events by vault or address

Analytics

Tool	Description
`get_funding_stats`	Avg/min/max/annualized funding per market
`get_liquidation_levels`	Liquidated notional by price bucket (Builder or Enterprise key)
`get_vault_leaderboard`	Vaults ranked by net deposits (Builder or Enterprise key)

Signals

Tool	Description
`get_top_traders`	Traders ranked across all markets over 7, 30 or 90 days
`get_market_leaders`	Best traders on one market by profit factor and win rate
`get_early_movers`	Wallets whose large orders preceded moves in their direction
`get_trader_profile`	One wallet’s record: win rate, profit factor, PnL, best markets

Wallet analytics

Tool	Description
`get_user_state`	Open positions + margin for any wallet
`get_user_summary`	One-call wallet overview
`get_user_funding`	Funding paid/received per wallet
`get_user_maker_taker`	Maker/taker split per wallet
`get_user_ledger`	Vault deposits, withdrawals and transfers (account deposits up to 2026-06-06)
`get_user_pnl_series`	Per-wallet PnL time series
`get_pnl_leaderboard`	Wallets ranked by realized PnL
`get_market_top_wallets`	Top wallets for one market
`get_wallet_labels`	Whale / smart-money / vault labels
`get_markets_snapshot`	Every market’s mark, 24h change, open interest and funding

Cohorts & status

Tool	Description
`list_cohorts`	List predefined and custom wallet cohorts
`get_cohort_addresses`	Get the wallet addresses in a named cohort
`get_status`	Overall system status and per-venue freshness
`get_status_metrics`	Rolling-window API + pipeline + synthetic latency metrics
`get_status_history`	Uptime / freshness timeline (24h or 7d)

All tools are read-only. Versions before 0.7.0 also listed tools for retired endpoints (order book, order statuses, triggers, export); update to the latest package.

Claude Code setup

claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp

# with a free key
claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp \
  --header "Authorization: Bearer if_your_api_key"

Claude desktop and claude.ai setup

Open Settings → Connectors → Add custom connector, name it Ironflow and paste https://mcp.ironflow.sh/mcp. No sign-in is needed. For free-key limits, use https://mcp.ironflow.sh/mcp?key=if_your_api_key as the URL.

Cursor setup

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "ironflow": {
      "url": "https://mcp.ironflow.sh/mcp"
    }
  }
}

To use a key, add "headers": { "Authorization": "Bearer if_your_api_key" } next to url.

Access levels

No key is needed: keyless calls get 10 requests per minute and 24 hours of history. For 60 requests per minute and 30 days, get a free key at ironflow.sh/key. A malformed key is rejected rather than silently treated as keyless. Once connected, you can ask:

“What’s the current BTC funding rate on Hyperliquid?”

“Show me the last 20 liquidations for ETH-PERP.”

“What’s the open interest across BTC and ETH perpetuals?”

“List the top 10 PnL wallets from the last 30 days.”

“Reconstruct wallet 0xabc…‘s fills over the past week.”

“Show me the last 50 trades on Felix Exchange’s GAS-PERP.” (HIP-3: flx:GAS-PERP)

“Compare GOLD-PERP volume across every HIP-3 builder over the last 7 days.”

Run it locally instead

The same server runs over stdio with Node.js 18+, for clients without remote MCP support or offline setups:

{
  "mcpServers": {
    "ironflow": {
      "command": "npx",
      "args": ["-y", "@ironflowsh/mcp"],
      "env": { "IRONFLOW_API_KEY": "if_your_api_key" }
    }
  }
}

The env block is optional. In Claude Code: claude mcp add ironflow -- npx -y @ironflowsh/mcp.

HIP-4 prediction markets in agent context

Outcome contracts (market_class: "prediction") live in the same MCP tool surface — list_markets, get_recent_trades, and get_candles all accept HIP-4 display symbols (e.g. BTC-78213-20260503-Yes) without any special-casing. This makes prediction markets first-class for natural-language workflows:

“What’s the implied probability that BTC closes above $78K tomorrow?” → agent calls get_recent_trades on BTC-78213-20260503-Yes, returns the latest fill price between 0 and 1.

“Show every active prediction market.” → agent calls list_markets with market_class=prediction.

The get_funding_rates, get_open_interest, and get_mark_prices tools return INVALID_MARKET_CLASS for prediction symbols — those concepts don’t apply to fully-collateralized binaries. See HIP-4 Outcomes for the symbol scheme and resolution metadata structure.

Custom MCP tools

Build your own MCP tools on top of the REST API with plain fetch:

TypeScript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-tools", version: "1.0.0" });
const headers: Record<string, string> = process.env.IRONFLOW_API_KEY
  ? { Authorization: `Bearer ${process.env.IRONFLOW_API_KEY}` }
  : {}; // keyless works too

server.tool("get_whale_trades", { market: z.string(), min_size: z.number() }, async ({ market, min_size }) => {
  const url = `https://api.ironflow.sh/v1/trades?source=hyperliquid&market=${encodeURIComponent(market)}&limit=200`;
  const { data } = await (await fetch(url, { headers })).json();
  const whales = data.filter((t: { size: string }) => parseFloat(t.size) >= min_size);
  return { content: [{ type: "text", text: JSON.stringify(whales, null, 2) }] };
});

Getting Started

Concepts

Guides

Terminal

SDKs

Hyperliquid MCP server for AI agents

MCP Server

Ask anything (SQL)

Market data

Historical queries

Analytics

Signals

Wallet analytics

Cohorts & status

Claude Code setup

Claude desktop and claude.ai setup

Cursor setup

Access levels

Run it locally instead

HIP-4 prediction markets in agent context

Custom MCP tools

​MCP Server

​Ask anything (SQL)

​Market data

​Historical queries

​Analytics

​Signals

​Wallet analytics

​Cohorts & status

​Claude Code setup

​Claude desktop and claude.ai setup

​Cursor setup

​Access levels

​Run it locally instead

​HIP-4 prediction markets in agent context

​Custom MCP tools

MCP Server

Ask anything (SQL)

Market data

Historical queries

Analytics

Signals

Wallet analytics

Cohorts & status

Claude Code setup

Claude desktop and claude.ai setup

Cursor setup

Access levels

Run it locally instead

HIP-4 prediction markets in agent context

Custom MCP tools