> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironflow.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Hyperliquid MCP server for AI agents

> Connect Claude, Cursor or any MCP client to the hosted Ironflow MCP server for Hyperliquid fills, funding, wallets and read-only SQL. No install, no key needed.

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

```bash theme={null}
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):

```json theme={null}
{
  "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](https://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:

```json theme={null}
{
  "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](/concepts/hip4-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 TypeScript theme={null}
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) }] };
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.