io.github.ironflowsh/mcp

Official36 toolsLive

by ironflowsh · TypeScript

Read-only Hyperliquid data for AI agents: fills, candles, funding, liquidations, wallet analytics.

io.github.ironflowsh/mcp — MCP Server for Tick-Level Hyperliquid Market Data

The io.github.ironflowsh/mcp server provides tick-level Hyperliquid market data, including fills, L4 order book, funding, and liquidations, along with smart triggers. It is focused on delivering detailed exchange event and state information at the level of individual market updates.

🛠️ Key Features

Tick-level Hyperliquid market data
Fills
L4 book
Funding
Liquidations
Smart triggers

🚀 Use Cases

Monitor Hyperliquid market activity with granular event data
Consume L4 order book updates for trading or analytics
Track funding and liquidation events alongside fills
Drive logic based on “smart triggers”

⚡ Developer Benefits

Structured access to multiple Hyperliquid data categories (fills, L4 book, funding, liquidations, triggers)
Developer consumption aligned with an MCP server interface for market data workflows

⚠️ Limitations

Scope described only for Hyperliquid tick-level market data; no other venues or data types are specified

Topics

ai-agentshyperliquidmarket-datamcpmcp-servertrading

Captured live from the server via tools/list.

describe_data

Start here for any Hyperliquid question the other tools do not answer directly. Returns the SQL tables you can query with run_query (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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

run_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). Call describe_data first for columns and examples. 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.

Parameters2

sql	string	required	One ClickHouse SELECT (or WITH ... SELECT) over hl.* tables, without a FORMAT clause
max_rows	number	optional	Most rows to return (default 200, capped by your tier)

Raw schema

{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "description": "One ClickHouse SELECT (or WITH ... SELECT) over hl.* tables, without a FORMAT clause"
    },
    "max_rows": {
      "type": "number",
      "description": "Most rows to return (default 200, capped by your tier)"
    }
  },
  "required": [
    "sql"
  ]
}

get_wallet_behavior

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.

Parameters5

addresses	string	optional	Comma-separated wallet addresses (up to 50). Omit to list wallets instead.
label	string	optional	Only wallets carrying this label
sort_by	string	optional	Sort order when listing (default volume)
min_volume_usd	number	optional	Only wallets with at least this 30-day volume
limit	number	optional	Wallets to return (default 20, max 100)

Raw schema

{
  "type": "object",
  "properties": {
    "addresses": {
      "type": "string",
      "description": "Comma-separated wallet addresses (up to 50). Omit to list wallets instead."
    },
    "label": {
      "type": "string",
      "description": "Only wallets carrying this label",
      "enum": [
        "market_maker",
        "high_frequency",
        "whale",
        "directional",
        "consistent_winner",
        "big_loser",
        "revenge_sizing",
        "often_liquidated",
        "hip3_trader",
        "spot_trader",
        "prediction_trader"
      ]
    },
    "sort_by": {
      "type": "string",
      "description": "Sort order when listing (default volume)",
      "enum": [
        "volume",
        "pnl",
        "fills",
        "liquidations"
      ]
    },
    "min_volume_usd": {
      "type": "number",
      "description": "Only wallets with at least this 30-day volume"
    },
    "limit": {
      "type": "number",
      "description": "Wallets to return (default 20, max 100)"
    }
  },
  "required": []
}

get_price

Latest mark price of a Hyperliquid market: native perps, HIP-3 builder perps (e.g. xyz:NVDA-PERP) and spot.

Parameters1

market

string

required

Market symbol — native HL perp (e.g. "BTC-PERP", "ETH-PERP") or HIP-3 builder market namespaced as "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP", "xyz:NVDA-PERP")

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\", \"ETH-PERP\") or HIP-3 builder market namespaced as \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\", \"xyz:NVDA-PERP\")"
    }
  },
  "required": [
    "market"
  ]
}

get_recent_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.

Parameters2

market	string	required	Market symbol — native HL perp (e.g. "BTC-PERP", "ETH-PERP") or HIP-3 builder market namespaced as "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP", "xyz:NVDA-PERP")
limit	number	optional	Number of trades to return (1-100, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\", \"ETH-PERP\") or HIP-3 builder market namespaced as \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\", \"xyz:NVDA-PERP\")"
    },
    "limit": {
      "type": "number",
      "description": "Number of trades to return (1-100, default 20)"
    }
  },
  "required": [
    "market"
  ]
}

get_candles

OHLCV candles for a Hyperliquid market, computed from tick-level trades.

Parameters3

market	string	required	Market symbol — native HL perp (e.g. "BTC-PERP", "ETH-PERP") or HIP-3 builder market namespaced as "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP", "xyz:NVDA-PERP")
interval	string	optional	Candle interval (1m, 5m, 15m, 1h, 4h, 1d). Default: 1h
limit	number	optional	Number of candles to return (1-500, default 24)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\", \"ETH-PERP\") or HIP-3 builder market namespaced as \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\", \"xyz:NVDA-PERP\")"
    },
    "interval": {
      "type": "string",
      "description": "Candle interval (1m, 5m, 15m, 1h, 4h, 1d). Default: 1h",
      "enum": [
        "1m",
        "5m",
        "15m",
        "1h",
        "4h",
        "1d"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Number of candles to return (1-500, default 24)"
    }
  },
  "required": [
    "market"
  ]
}

get_funding_rates

Hourly funding rate history for a Hyperliquid perp, including HIP-3 builder perps. A positive rate means longs pay shorts.

Parameters2

market	string	required	Market symbol — native HL perp (e.g. "BTC-PERP", "ETH-PERP") or HIP-3 builder market namespaced as "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP", "xyz:NVDA-PERP")
limit	number	optional	Number of funding rate entries (1-100, default 10)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\", \"ETH-PERP\") or HIP-3 builder market namespaced as \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\", \"xyz:NVDA-PERP\")"
    },
    "limit": {
      "type": "number",
      "description": "Number of funding rate entries (1-100, default 10)"
    }
  },
  "required": [
    "market"
  ]
}

get_open_interest

Latest open interest for a Hyperliquid perp.

Parameters1

market

string

required

Market symbol — native HL perp (e.g. "BTC-PERP", "ETH-PERP") or HIP-3 builder market namespaced as "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP", "xyz:NVDA-PERP")

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\", \"ETH-PERP\") or HIP-3 builder market namespaced as \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\", \"xyz:NVDA-PERP\")"
    }
  },
  "required": [
    "market"
  ]
}

get_liquidations

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.

Parameters2

market	string	required	Market symbol — native HL perp (e.g. "BTC-PERP", "ETH-PERP") or HIP-3 builder market namespaced as "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP", "xyz:NVDA-PERP")
limit	number	optional	Number of liquidation events (1-100, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\", \"ETH-PERP\") or HIP-3 builder market namespaced as \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\", \"xyz:NVDA-PERP\")"
    },
    "limit": {
      "type": "number",
      "description": "Number of liquidation events (1-100, default 20)"
    }
  },
  "required": [
    "market"
  ]
}

get_liquidation_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.

Parameters2

minutes	number	optional	Lookback in minutes (default 60, max 240)
market	string	optional	Optional market filter (e.g. "BTC-PERP")

Raw schema

{
  "type": "object",
  "properties": {
    "minutes": {
      "type": "number",
      "description": "Lookback in minutes (default 60, max 240)"
    },
    "market": {
      "type": "string",
      "description": "Optional market filter (e.g. \"BTC-PERP\")"
    }
  },
  "required": []
}

get_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.

Parameters3

address	string	required	Wallet address (e.g. 0x...)
market	string	optional	Optional market filter — native HL (e.g. "BTC-PERP") or HIP-3 builder market "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP")
limit	number	optional	Number of fills (1-100, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Wallet address (e.g. 0x...)"
    },
    "market": {
      "type": "string",
      "description": "Optional market filter — native HL (e.g. \"BTC-PERP\") or HIP-3 builder market \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\")"
    },
    "limit": {
      "type": "number",
      "description": "Number of fills (1-100, default 20)"
    }
  },
  "required": [
    "address"
  ]
}

get_mark_prices

Mark price and oracle price series for a Hyperliquid perp.

Parameters1

market

string

required

Market symbol — native HL perp (e.g. "BTC-PERP") or HIP-3 builder market "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP")

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\") or HIP-3 builder market \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\")"
    }
  },
  "required": [
    "market"
  ]
}

get_vault_operations

Deposits into and withdrawals from one Hyperliquid vault or one depositor. Pass vault, address, or both; at least one is required (HLP is 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303). For flows across all vaults use get_vault_leaderboard.

Parameters3

vault	string	optional	Vault address (vault or address is required)
address	string	optional	Depositor address (vault or address is required)
limit	number	optional	Number of events (1-100, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "vault": {
      "type": "string",
      "description": "Vault address (vault or address is required)"
    },
    "address": {
      "type": "string",
      "description": "Depositor address (vault or address is required)"
    },
    "limit": {
      "type": "number",
      "description": "Number of events (1-100, default 20)"
    }
  },
  "required": []
}

get_liquidation_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.

Parameters2

market	string	required	Market symbol — native HL perp (e.g. "BTC-PERP") or HIP-3 builder market "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP")
bucket_size	string	optional	Price bucket size (1, 5, 10, 50, 100, 500, 1000, 5000). Default: 100

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\") or HIP-3 builder market \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\")"
    },
    "bucket_size": {
      "type": "string",
      "description": "Price bucket size (1, 5, 10, 50, 100, 500, 1000, 5000). Default: 100"
    }
  },
  "required": [
    "market"
  ]
}

get_vault_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.

Parameters1

limit

number

optional

Number of vaults (default 10, max 1000)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Number of vaults (default 10, max 1000)"
    }
  },
  "required": []
}

get_funding_stats

Funding statistics per time bucket for a Hyperliquid perp: average, minimum, maximum and annualized rate.

Parameters3

market	string	required	Market symbol — native HL perp (e.g. "BTC-PERP") or HIP-3 builder market "<issuer>:<base>-PERP" (e.g. "flx:GAS-PERP")
interval	string	optional	Time interval (1h, 4h, 8h, 1d, 7d). Default: 1d
limit	number	optional	Number of data points (default 7)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol — native HL perp (e.g. \"BTC-PERP\") or HIP-3 builder market \"<issuer>:<base>-PERP\" (e.g. \"flx:GAS-PERP\")"
    },
    "interval": {
      "type": "string",
      "description": "Time interval (1h, 4h, 8h, 1d, 7d). Default: 1d",
      "enum": [
        "1h",
        "4h",
        "8h",
        "1d",
        "7d"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Number of data points (default 7)"
    }
  },
  "required": [
    "market"
  ]
}

get_user_state

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?'

Parameters1

address

string

required

0x-prefixed 20-byte hex address

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    }
  },
  "required": [
    "address"
  ]
}

get_user_funding

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.

Parameters6

address	string	required	0x-prefixed 20-byte hex address
market	string	optional	Optional market filter (e.g. BTC-PERP)
from	number	optional	Unix ms window start (inclusive)
to	number	optional	Unix ms window end (exclusive)
bucket	string	optional	Aggregation bucket; default 1d
limit	number	optional	Most recent rows to return (default 200)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    },
    "market": {
      "type": "string",
      "description": "Optional market filter (e.g. BTC-PERP)"
    },
    "from": {
      "type": "number",
      "description": "Unix ms window start (inclusive)"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end (exclusive)"
    },
    "bucket": {
      "type": "string",
      "enum": [
        "1h",
        "1d",
        "raw"
      ],
      "description": "Aggregation bucket; default 1d"
    },
    "limit": {
      "type": "number",
      "description": "Most recent rows to return (default 200)"
    }
  },
  "required": [
    "address"
  ]
}

get_user_maker_taker

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.

Parameters4

address	string	required	0x-prefixed 20-byte hex address
market	string	optional	Optional market filter
from	number	optional	Unix ms window start
to	number	optional	Unix ms window end

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    },
    "market": {
      "type": "string",
      "description": "Optional market filter"
    },
    "from": {
      "type": "number",
      "description": "Unix ms window start"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end"
    }
  },
  "required": [
    "address"
  ]
}

get_user_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.

Parameters5

address	string	required	0x-prefixed 20-byte hex address
from	number	optional	Unix ms window start
to	number	optional	Unix ms window end
event_types	string	optional	Comma-separated type filter (deposit,withdrawal,vault_deposit,vault_withdraw,vault_transfer_in,vault_transfer_out)
limit	number	optional	Max entries, default 1000, cap 10000

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    },
    "from": {
      "type": "number",
      "description": "Unix ms window start"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end"
    },
    "event_types": {
      "type": "string",
      "description": "Comma-separated type filter (deposit,withdrawal,vault_deposit,vault_withdraw,vault_transfer_in,vault_transfer_out)"
    },
    "limit": {
      "type": "number",
      "description": "Max entries, default 1000, cap 10000"
    }
  },
  "required": [
    "address"
  ]
}

get_pnl_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.

Parameters4

from	number	optional	Unix ms window start (default 30d ago)
to	number	optional	Unix ms window end (default now)
limit	number	optional	Number of rows, max 200, default 50
sort_by	string	optional	Ranking metric

Raw schema

{
  "type": "object",
  "properties": {
    "from": {
      "type": "number",
      "description": "Unix ms window start (default 30d ago)"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end (default now)"
    },
    "limit": {
      "type": "number",
      "description": "Number of rows, max 200, default 50"
    },
    "sort_by": {
      "type": "string",
      "description": "Ranking metric",
      "enum": [
        "realized_pnl",
        "loss",
        "volume"
      ]
    }
  },
  "required": []
}

get_market_top_wallets

Top wallets on one Hyperliquid market by volume or realized PnL, up to 200 rows.

Parameters5

market	string	required	Market symbol (e.g. 'BTC-PERP' or 'flx:GAS-PERP')
from	number	optional	Unix ms window start (default 24h ago)
to	number	optional	Unix ms window end (default now)
limit	number	optional	Number of rows, max 200, default 25
sort_by	string	optional	Ranking metric

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol (e.g. 'BTC-PERP' or 'flx:GAS-PERP')"
    },
    "from": {
      "type": "number",
      "description": "Unix ms window start (default 24h ago)"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end (default now)"
    },
    "limit": {
      "type": "number",
      "description": "Number of rows, max 200, default 25"
    },
    "sort_by": {
      "type": "string",
      "description": "Ranking metric",
      "enum": [
        "volume",
        "realized_pnl"
      ]
    }
  },
  "required": [
    "market"
  ]
}

get_markets_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.

Parameters6

market_class	string	optional	Filter to one class
issuer	string	optional	HIP-3 builder code (e.g. 'xyz'). Omit to include every issuer.
sort_by	string	optional	Ranking key (default volume). funding_rate is hourly; positive means longs pay shorts.
order	string	optional	desc (default) or asc
limit	number	optional	Rows to return (1-200, default 25)
min_volume_usd	number	optional	Skip markets with less 24h volume than this (USD)

Raw schema

{
  "type": "object",
  "properties": {
    "market_class": {
      "type": "string",
      "description": "Filter to one class",
      "enum": [
        "perp",
        "spot",
        "prediction",
        "option"
      ]
    },
    "issuer": {
      "type": "string",
      "description": "HIP-3 builder code (e.g. 'xyz'). Omit to include every issuer."
    },
    "sort_by": {
      "type": "string",
      "description": "Ranking key (default volume). funding_rate is hourly; positive means longs pay shorts.",
      "enum": [
        "volume",
        "open_interest",
        "funding",
        "abs_funding",
        "change_24h",
        "abs_change_24h"
      ]
    },
    "order": {
      "type": "string",
      "description": "desc (default) or asc",
      "enum": [
        "desc",
        "asc"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Rows to return (1-200, default 25)"
    },
    "min_volume_usd": {
      "type": "number",
      "description": "Skip markets with less 24h volume than this (USD)"
    }
  },
  "required": []
}

get_user_summary

One Hyperliquid wallet's stats over a window: volume, realized PnL, fill count, win rate, maker share and markets traded.

Parameters3

address	string	required	0x-prefixed 20-byte hex address
from	number	optional	Unix ms window start (default 24h ago)
to	number	optional	Unix ms window end (default now)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    },
    "from": {
      "type": "number",
      "description": "Unix ms window start (default 24h ago)"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end (default now)"
    }
  },
  "required": [
    "address"
  ]
}

get_wallet_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.

Parameters3

addresses	string	optional	Comma-separated wallet addresses to look up
whale_top_n	number	optional	Top N whales to include (max 500, default 100)
smart_top_n	number	optional	Top N smart-money wallets to include (max 500, default 100)

Raw schema

{
  "type": "object",
  "properties": {
    "addresses": {
      "type": "string",
      "description": "Comma-separated wallet addresses to look up"
    },
    "whale_top_n": {
      "type": "number",
      "description": "Top N whales to include (max 500, default 100)"
    },
    "smart_top_n": {
      "type": "number",
      "description": "Top N smart-money wallets to include (max 500, default 100)"
    }
  },
  "required": []
}

get_user_pnl_series

Realized PnL curve of a Hyperliquid wallet over time, bucketed (for example hourly or daily).

Parameters4

address	string	required	0x-prefixed 20-byte hex address
from	number	optional	Unix ms window start
to	number	optional	Unix ms window end (default now)
bucket_ms	number	optional	Bucket size in ms (e.g. 3600000 for 1h)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    },
    "from": {
      "type": "number",
      "description": "Unix ms window start"
    },
    "to": {
      "type": "number",
      "description": "Unix ms window end (default now)"
    },
    "bucket_ms": {
      "type": "number",
      "description": "Bucket size in ms (e.g. 3600000 for 1h)"
    }
  },
  "required": [
    "address"
  ]
}

get_top_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.

Parameters3

window	string	optional	Lookback window. Default 30d
sort	string	optional	Ranking. Default top
limit	number	optional	Number of traders (1-50, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "window": {
      "type": "string",
      "description": "Lookback window. Default 30d",
      "enum": [
        "7d",
        "30d",
        "90d"
      ]
    },
    "sort": {
      "type": "string",
      "description": "Ranking. Default top",
      "enum": [
        "top",
        "lowrisk",
        "new"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Number of traders (1-50, default 20)"
    }
  },
  "required": []
}

get_market_leaders

The best traders on one Hyperliquid market, ranked by profit factor then win rate, among wallets with at least 5 closed trades there.

Parameters3

market	string	required	Market symbol (e.g. "BTC-PERP", "xyz:NVDA-PERP")
window	string	optional	Lookback window. Default 30d
limit	number	optional	Number of traders (1-50, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol (e.g. \"BTC-PERP\", \"xyz:NVDA-PERP\")"
    },
    "window": {
      "type": "string",
      "description": "Lookback window. Default 30d",
      "enum": [
        "7d",
        "30d",
        "90d"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Number of traders (1-50, default 20)"
    }
  },
  "required": [
    "market"
  ]
}

get_early_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.

Parameters3

market	string	required	Market symbol (e.g. "BTC-PERP", "xyz:SKHX-PERP")
window	string	optional	Lookback window. Default 30d
limit	number	optional	Number of wallets (1-25, default 10)

Raw schema

{
  "type": "object",
  "properties": {
    "market": {
      "type": "string",
      "description": "Market symbol (e.g. \"BTC-PERP\", \"xyz:SKHX-PERP\")"
    },
    "window": {
      "type": "string",
      "description": "Lookback window. Default 30d",
      "enum": [
        "7d",
        "30d"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Number of wallets (1-25, default 10)"
    }
  },
  "required": [
    "market"
  ]
}

get_trader_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.

Parameters2

address	string	required	0x-prefixed 20-byte hex address
window	string	optional	Lookback window. Default 30d

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x-prefixed 20-byte hex address"
    },
    "window": {
      "type": "string",
      "description": "Lookback window. Default 30d",
      "enum": [
        "7d",
        "30d",
        "90d"
      ]
    }
  },
  "required": [
    "address"
  ]
}

list_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

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_cohort_addresses

Get the wallet addresses in a specific cohort

Parameters1

name

string

required

Cohort name (e.g. top_pnl_30d, high_volume_30d, whale_fills, or a custom cohort name)

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Cohort name (e.g. top_pnl_30d, high_volume_30d, whale_fills, or a custom cohort name)"
    }
  },
  "required": [
    "name"
  ]
}

get_status

Get system status, data freshness, and venue health (unauthenticated)

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_status_metrics

Get rolling-window API + pipeline + synthetic performance metrics (unauthenticated)

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_status_history

Get an uptime / freshness timeline. period: '24h' (default) or '7d' (unauthenticated)

Parameters1

period

string

optional

Lookback window. '24h' (default) or '7d'.

Raw schema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "description": "Lookback window. '24h' (default) or '7d'.",
      "enum": [
        "24h",
        "7d"
      ]
    }
  },
  "required": []
}

list_markets

Active Hyperliquid markets with display symbol, class (perp, spot, prediction), HIP-3 issuer and base asset. Use search to find how a market is named (e.g. search 'nvda' finds xyz:NVDA-PERP).

Parameters5

source	string	optional	Venue. Defaults to 'hyperliquid'.
market_class	string	optional	Market class. Omit to return perp + spot + prediction. 'prediction' filters to HIP-4 outcome contracts.
issuer	string	optional	HIP-3 issuer code (e.g. 'flx'). Pass empty string '' to return only native non-builder markets. Omit to include every issuer.
search	string	optional	Case-insensitive match on symbol, base asset or Hyperliquid coin
limit	number	optional	Rows to return (default 100)

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Venue. Defaults to 'hyperliquid'."
    },
    "market_class": {
      "type": "string",
      "description": "Market class. Omit to return perp + spot + prediction. 'prediction' filters to HIP-4 outcome contracts.",
      "enum": [
        "perp",
        "spot",
        "prediction",
        "option"
      ]
    },
    "issuer": {
      "type": "string",
      "description": "HIP-3 issuer code (e.g. 'flx'). Pass empty string '' to return only native non-builder markets. Omit to include every issuer."
    },
    "search": {
      "type": "string",
      "description": "Case-insensitive match on symbol, base asset or Hyperliquid coin"
    },
    "limit": {
      "type": "number",
      "description": "Rows to return (default 100)"
    }
  },
  "required": []
}

README.md5 KBView on GitHub

@ironflowsh/mcp

MCP server for Ironflow: read-only Hyperliquid market data and wallet analytics for Claude, Cursor and any MCP client. It covers native perps, HIP-3 builder markets, HIP-4 outcome markets and spot. 36 tools, all read-only, including run_query for read-only SQL over every Hyperliquid fill, wallet, funding and liquidation table.

No API key needed to start: keyless calls get 10 requests per minute and 24 hours of history. A free key from ironflow.sh/key raises that to 60 requests per minute and 30 days.

Example questions

"What were the largest Hyperliquid liquidations in the last 24 hours?"

"Show funding rates for the HIP-3 markets right now."

"List the HIP-4 outcome markets that are live."

"Summarize this wallet's last 30 days: PnL, fees, maker share, funding paid."

Hosted server (no install)

Connect by URL: https://mcp.ironflow.sh/mcp (Streamable HTTP).

bash

# Claude Code
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: Settings → Connectors → Add custom connector, paste the URL.

Cursor (~/.cursor/mcp.json or a project's .cursor/mcp.json):

json

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

Clients that cannot send headers can pass the key as ?key=if_your_api_key on the URL.

Local server

bash

npx -y @ironflowsh/mcp

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

json

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

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

Tools

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_liquidations, get_liquidation_summary, 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_liquidation_levels and get_vault_leaderboard (these two need a Builder or Enterprise key)

Signals: get_top_traders, get_market_leaders, get_early_movers, get_trader_profile

Wallet analytics: get_user_state, 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

Fill history covers a rolling 12 months. There is no order book, order status or streaming tool.

Configuration

Env var	Default
`IRONFLOW_API_KEY`	optional; free key at ironflow.sh/key
`IRONFLOW_API_URL`	`https://api.ironflow.sh`
`PORT` (HTTP server)	`8080`
`MCP_LOG_SALT` (HTTP server)	random per process; keys the caller hash in the access log

Usage data

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 and a salted hash of the caller's IP. It never logs IPs or API keys.

License

MIT

Install

Tools (36)

describe_datarun_queryget_wallet_behaviorget_priceget_recent_tradesget_candlesget_funding_ratesget_open_interest

Configuration

Environment variables

IRONFLOW_API_KEYsecret

Optional Ironflow API key. Keyless calls get 10 requests per minute; a free key from https://ironflow.sh/key gives 60.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ironflowsh/mcp@0.9.0"
      ],
      "env": {
        "IRONFLOW_API_KEY": "<YOUR_IRONFLOW_API_KEY>"
      }
    }
  }
}

io.github.ironflowsh/mcp — MCP Server for Tick-Level Hyperliquid Market Data

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

describe_data

run_query

get_wallet_behavior

get_price

get_recent_trades

get_candles

get_funding_rates

get_open_interest

get_liquidations

get_liquidation_summary

get_fills

get_mark_prices

get_vault_operations

get_liquidation_levels

get_vault_leaderboard

get_funding_stats

get_user_state

get_user_funding

get_user_maker_taker

get_user_ledger

get_pnl_leaderboard

get_market_top_wallets

get_markets_snapshot

get_user_summary

get_wallet_labels

get_user_pnl_series

get_top_traders

get_market_leaders

get_early_movers

get_trader_profile

list_cohorts

get_cohort_addresses

get_status

get_status_metrics

get_status_history

list_markets

@ironflowsh/mcp

Example questions

Hosted server (no install)

Local server

Tools

Configuration

Usage data

Links

License

Install

Configuration

Related servers