Coinversaa/mcp-server

Report the data window (start/end or latest row) and freshness stamp of each dataset behind this server, with the API route each figure came from — check window and freshness before relying on a historical range or citing a date. Datasets: trades (indexed trade history, /pulse/stats), builder_ledger (fee ledger + attribution coverage), census (chain-state stamp), hip4 (latest outcome fill), liquidations (risk-route availability/freshness), lifecycles (latest close; rolling 90-day window), cohort_history, book (L4 order-book rollups: coins covered, latest L1 height/time and age; snapshot-derive…

Measure overlap between HIP-4 outcome traders and perp traders over a recent window. Returns outcome trader count, perp trader count, overlap count, and overlap percentage. Requires a Pro-or-higher key.

Get daily HIP-4 volume trajectory: fills, unique trades, unique wallets, contracts, and notional USDH by day. Use for outcome-market activity trends. HIP-4 fills are indexed from mainnet launch (2026-05-02; the API clamps every look-back to it) — see data_coverage for freshness.

Return the most active HIP-4 outcomes over a recent window, ranked by fill count. Includes outcome/question metadata when available.

Get details for one HIP-4 outcome contract by outcome ID. Returns metadata when available plus side tokens, fills, unique wallets, notional USDH, and trading timestamps.

Get recent real fills for one HIP-4 outcome. Excludes settlement, pair-redeem, and auction-phase fills. Returns trade time, wallet, side, price, size, PnL, and fee.

Get the full HIP-4 summary for one outcome across both sides: fills, unique wallets, contracts, side notional, total notional, realized PnL, and trading window. Requires a Starter-or-higher key.

List active HIP-4 outcome contracts that traded recently. Returns outcome IDs, question metadata when available, side tokens, fills, unique wallets, notional USDH, and first/last traded timestamps. Use when users ask what prediction/outcome markets are active. Outcomes are sorted by notionalUsdh descending and capped at `limit` (default 25, max 200; the API route has no paging, so the cap is applied by the connector) — the response carries count (returned), totalCount, truncated and a note; raise limit or shorten hours to see more. HIP-4 fills are indexed from mainnet launch (2026-05-02; the A…

Join one HIP-4 outcome's current net-positive holders to currently open perp positions on the same underlying asset. Returns per-side wallet counts, open-position overlap, long/short wallet counts, net underlying position, underlying notional, aligned vs hedge counts, prediction-native counts, and top wallets with signal labels. Use when users ask whether outcome traders are already exposed to the same asset, whether a side is directional or hedged, or which large outcome holders have no underlying perp exposure. Requires a Pro-or-higher key.

List HIP-4 question metadata from Hyperliquid outcomeMeta, including question IDs, descriptions, fallback outcomes, named outcomes, settlement metadata, and parsed expiry/threshold fields when present.

List recent HIP-4 settlements. Returns outcome ID, settlement time, winning side when determinable, winner/loser fill counts, winner payouts, and loser losses.

Rank top HIP-4 outcome traders by recent outcome activity. Returns address, fills, distinct outcomes, contracts, notional USDH, and realized PnL. Requires a Starter-or-higher key.

Get one wallet's HIP-4 outcome history: outcome ID, side index, side token, fills, net shares, gross bought/sold USDH, realized PnL, and first/last traded. Requires a Starter-or-higher key. Rows are sorted by gross notional (grossBoughtUsdh + grossSoldUsdh) descending and capped at `limit` (default 50, max 200; the API route has no paging, so the cap is applied by the connector) — the response carries count (returned), totalCount, truncated and a note; raise limit or shorten days to see more. The API clamps days to 90 and to HIP-4 mainnet launch (2026-05-02) — see data_coverage.

Lookup one asset by canonical name or synonym. Returns every venue it trades on, collateral tokens, open interest per venue, and synonyms list. Accepts both canonical names (GOLD, BTC) and synonyms (PAXG, XAUT) — the server resolves them. Use when the user mentions a specific asset and you need its venue availability.

Directory of every canonical asset that trades on Hyperliquid or any builder dex, grouped by economic exposure (not by venue ticker). Each asset entry lists its synonyms (e.g. PAXG is a synonym of GOLD), which venues it trades on, aggregated open interest, and a cross-market flag (listed on 2+ venues). Prefer this over list_markets when the user asks 'what assets are available?', 'which venues is GOLD on?', or 'show me cross-market assets'.

CANONICAL market discovery tool. Returns every trading symbol on Hyperliquid and its builder dexes with dex, mark price, 24h volume, funding rate, open interest, and 24h change. Use this whenever the user asks 'what markets are available?', mentions a commodity (gold, silver, oil), stock (TSLA, AAPL, NVDA), or builder-dex market. For asset-level grouping across venues, use list_assets instead.

See what each trader cohort is doing on a specific coin RIGHT NOW. Returns the net long/short bias for every tier (Apex, Sharps, Middleweights, etc.) on the given coin. Answers questions like 'are the Sharps traders long or short ETH?'

Get historical cohort bias data for a specific coin. Use this when a user asks 'were smart-money cohorts accumulating or exiting?' or 'which tier flipped first?'. Returns hourly net-bias snapshots for each tier or for a specific tier over time.

Get the historical risk lane for a coin. Best for questions like 'how did this setup become fragile?' or 'did smart money rotate before the move?'. Returns hourly OI, long/short history, cohort rotation, candle data, and liquidation counts over time; by default the minute-level markDislocations section is omitted (it alone is ~700 rows per 12h). Pass include=[..., 'markDislocations'] to add it bucketed to 1 hour (the max-|basisPct| minute per hour), or use live_mark_dislocations for finer resolution. The response lists sections and omittedSections. Freshness and availability are in the respons…

Get the current risk snapshot for a single coin. Use this when a user asks 'is BTC crowded?', 'who is holding the risk?', or 'how liquidation-prone is this market right now?'. Returns OI, wallet count, long/short posture, position-size concentration, top positions, liquidation heatmap, and 7-day liquidation totals.

Get a liquidation heatmap for any coin. Shows where liquidation clusters are across price levels — essential for identifying support/resistance and potential squeeze zones.

Get an aggregated liquidation summary over a time window. This is the best liquidation tool for summaries, rankings, and trend analysis. Returns event count, penalty fees, closed PnL, per-coin rollups, and a liquidation timeline.

Get long/short ratio data. Without a coin, returns the global ratio across all Hyperliquid. With a coin, returns that specific pair's ratio. Optionally include historical data over the last N hours.

Get historical mark/oracle dislocation data for a coin. Use this to answer questions like 'did basis stress or oracle drift show up before liquidations?'. Returns timestamped mark price, oracle price, and basis percentage over the requested window — default 168 hours (7 days), max 720 hours (30 days). The source series is one row per minute; the connector buckets it by `resolution` (default 5m: the max-|basisPct| minute in each 5-minute bucket; 1h likewise; 1m = raw) and returns at most `limit` rows (default 500, newest kept), with totalCount, truncated and a note when rows were dropped. For 7…

Official per-dex open interest for a coin, sourced from Hyperliquid's Info API (not derived from live_positions). Returns hourly snapshots with open interest, mark price, and 24h notional volume. Use when an agent needs venue-reported ground truth, per-dex breakdown, or wants to cross-check computed OI against official numbers. Default 7 days, max 30 days.

Get historical open interest data for any coin on Hyperliquid, or global OI across all coins. Best for identifying accumulation/distribution phases, market conviction shifts, and whether a move was backed by positioning. Default 7 days, max 30 days.

Get real liquidation events from the syncer. Best for questions like 'where did forced unwind activity actually hit?' or 'show me BTC liquidations over the last 30 days'. Returns wallet, coin, penalty fee, and closed PnL.

Get the exchange-wide market risk snapshot. Best for questions like 'what looks fragile right now?' or 'which coins are most crowded?'. Returns total open interest, leverage, crowding concentration, near-liquidation exposure, 7-day liquidation totals, and the top coins where positioning looks most fragile.

Get historical hourly open interest snapshots (notional USD). Supports per-coin filtering or global exchange aggregation. Max range is 30 days.

Get the order book (bid/ask depth) for any trading pair on Hyperliquid. Shows price levels and sizes on both sides. Essential for understanding liquidity, spread, and potential support/resistance.

Get all open positions for any wallet address on Hyperliquid. Shows current entries, sizes, unrealized PnL, and leverage for each position.

Get current mark price for any trading pair on Hyperliquid. Use standard symbols (BTC, ETH, SOL) or builder dex format (xyz:SILVER, km:OIL, cash:TSLA).

Get recent 1-minute candle history for a market. Best for short intraday structure checks, recent momentum, and micro-pullback analysis. This MCP tool is intentionally capped to the most recent 12 hours so agents do not fetch huge minute-bar dumps in one call.

Distinct wallets that filled at least one perp trade in the last 24h, exchange-wide, plus total match count. The 'daily active traders' headline number. Cached up to 120s.

Find wallets that blew up and never recovered — cumulative realized PnL hit a deep trough and is still underwater. Returns wallet, trough depth, and current cumulative PnL. Use for 'who got rekt and stayed rekt?'.

Get the most catastrophic individual liquidations across Hyperliquid — large forced closes ranked by loss. Returns wallet, coin, side, entry VWAP, peak size, realized PnL, penalty fee, liquidation method, and liquidator address. Use for 'who got wrecked hardest?' and post-mortem analysis. Default returns $10k+ losses.

Get the biggest winning or losing trades across all of Hyperliquid. Use type='wins' for the largest profitable trades, or type='losses' for the largest losses. Useful for market sentiment and narrative analysis.

Find the most fee-efficient traders: highest realized PnL per dollar of fees paid. Returns wallet, total PnL, total fees, PnL-per-fee-dollar ratio, and lifecycle count. Use for 'who extracts the most edge per dollar spent on fees?'. minPnl/minFees gates filter out noise.

Get historical hourly bias snapshots for trader cohorts. Returns net long/short notional and account counts per tier — 32 tier rows per hour (16 PnL + 16 size tiers), so filter with tierType and/or tier for a readable series. Use this to see how different groups (whales, smart money) have shifted their positioning over time. Supports per-coin or global aggregate; the API default window is 7d, max 30d. Returns { rows, totalCount, truncated, note? } with rows newest first, capped at `limit` (default 100); when truncated, narrow with tierType/tier or a shorter since, or raise limit (max 2000). Co…

Get historical performance data for a specific trader cohort over time. Shows how a tier's aggregate PnL, trade count, and activity have changed day-by-day. Use to spot trends like 'the sharps (Sharps) tier has been increasingly bearish over the last month.'

Get historical daily performance statistics for trader cohorts. Returns PnL, volume, trade counts, and active trader counts per tier — 32 tier rows per day, so filter with tierType and/or tier for a readable series. Use this to track the consistency and profitability of different groups over time. API default window 30d, max 30d. Returns { rows, totalCount, truncated, note? } sorted by date (newest first) then tierType and tier, capped at `limit` (default 100); when truncated, narrow with tierType/tier or a shorter since, or raise limit (max 2000). Cohort history is served for up to the last 3…

See what a specific trader cohort is holding RIGHT NOW. For example, get all live positions held by 'apex' (Apex) tier traders or 'heavyweights' (Heavyweights) size wallets. This is real-time whale intelligence.

How concentrated profit is WITHIN a recent-tier cohort: percentile bands of the cohort's wallets and each band's share of the cohort's total PnL. Returns band, wallet count, band PnL, % of tier PnL, and tier total wallets. Use for 'within the hot apex (Apex) cohort, do a few wallets carry everything?'.

Per-wallet lifecycle stats for a cohort defined by its LAST-30-DAY tier: lifecycles, wins, losses, liquidations, total PnL, fees, avg hold, biggest win/loss, plus the wallet's recent pnl/size tier labels. Use for position-level analysis of who is currently printing.

Live positions held by a cohort defined by its LAST-30-DAY tier (pnl_tier_recent / size_tier_recent), not lifetime tier. Surfaces what currently-printing wallets are positioned for right now — catches regime changes the all-time pulse_cohort_positions misses.

Top closed position lifecycles by a cohort defined by its LAST-30-DAY tier: the biggest/most notable open->close cycles from currently-printing wallets, with entry/exit VWAP, hold duration, realized PnL, fees, and liquidation flag.

Recent trades by a cohort defined by its LAST-30-DAY tier (pnl_tier_recent / size_tier_recent). Shows what currently-printing wallets have been trading in the window — real-time alpha weighted to who is hot NOW, not all-time.

Get behavioral cohort analysis across every tracked wallet on Hyperliquid. Returns PnL tiers (Apex/apex, Sharps/sharps, Grinders/grinders, Scrapers/scrapers, The Crowd/crowd, Bleeders/bleeders, Trapped/trapped, Blown Out/blown_out) and size tiers (Heavyweights/heavyweights, Cruiserweights/cruiserweights, Middleweights/middleweights, etc). Response payloads still use legacy slugs (money_printer, leviathan, ...). Each tier shows wallet count, avg PnL, avg win rate, and total volume. For the current tracked-wallet total, call pulse_global_stats first.

See every trade a specific cohort has made recently. For example: 'show me all trades the apex (Apex) tier made in the last hour.'

Per-coin profit pools split into winners vs losers vs net. Returns coin, lifecycles, unique wallets, winners pool, losers pool, net PnL, winning/losing lifecycle counts, and total fees. Use for 'which coins are net wealth creators vs destroyers?'.

Find the top earner(s) per coin within the window. perCoinRank=1 returns only the #1 earner ('king') of each coin; higher values return the top-N per coin. Returns coin, wallet, coin PnL, fees, lifecycle count, and rank. Use for 'who owns BTC?' / 'who is the best trader of each market?'.

Side-by-side comparison of 2-5 wallets via their lifecycle summaries — win rate, total/avg PnL, hold duration, biggest win/loss, fees, liquidations. Use for head-to-head trader comparison ('who is the better trader, A or B?').

Cross-market aggregation for one asset: per-venue long/short positions, notional, net bias, unique wallets, leverage, plus a cross-venue total. Also returns biasRange (max-min netBias across venues) to detect disagreement. Accepts canonical names or synonyms (e.g. PAXG resolves to GOLD). Use when the user asks 'is gold crowded?', 'do different dexes disagree on BTC direction?', 'total OI on ETH across all venues?'.

Top entities (owners, NOT wallets) ranked by combined gross open entry notional across all their sub-accounts. This is the deduplicated view a wallet leaderboard cannot give: a fund running 35 sub-accounts appears as ONE entity with its true combined book. System/protocol accounts are excluded. Each row: entity master address, wallet count, open position count, gross entry notional. Requires Pro tier.

Resolve ANY wallet to its owner entity: the master account, every named sub-account (and weaker 'linked' wallets), each member's open book, the COMBINED open positions across all of them, and a 'verified vs chain at block N' stamp. Answers 'who owns this wallet?' and 'what is this trader's real total book across all their accounts?' — sub-accounts trade independently on Hyperliquid, so per-wallet views undercount every multi-account trader. Note: vaults appear as named sub-accounts of their creator. Requires Pro tier.

Current open interest for the whole exchange by dex, with long/short notional split. Gross both-sides convention (matches HyperTracker/hl.eco headlines; halve for one-sided OI). Use for 'what's the OI on Hyperliquid / on xyz?', market-size questions, and long-vs-short balance checks. Cached up to 120s.

Exchange-wide position vitals by dex: open positions and wallets holding them, plus the 24h flow — positions closed, liquidations, and TOTAL REALIZED PNL across the whole exchange (gross profits/losses split). Answers 'how many positions are open on Hyperliquid?' and 'did traders collectively make or lose money today?' Cached up to 120s.

24h trading volume for the WHOLE exchange, split by dex: native Hyperliquid ('hl') plus every builder dex (xyz, hyna, ...), with per-dex match counts and distinct traders. Use for 'how much volume does Hyperliquid do?' — and note builder dexes are ~43% of it. Aggregates cached up to 120s.

Get global Hyperliquid trading statistics: total traders, trades, volume, PnL, and data coverage period. Use this to understand the overall scale of the market. dataStartDate/dataEndDate are the indexed trade window (2025-03-22 onward as of 0.11.4); data_coverage reports the window and freshness of every dataset.

Discover underrated high-performing traders who fly under the radar. Filters by minimum win rate, PnL, and trade count. These are skilled traders that most platforms don't surface.

Global PnL heatmap by UTC hour of position close. Returns, for each of the 24 hours, lifecycle count, total PnL, avg PnL, wins, and losses. Use for 'what time of day is most profitable to close?' / session-bias analysis.

Get ranked trader leaderboard. Sort by PnL, win rate, volume, score, or risk-adjusted returns. Filter by time period (day/week/month/allTime) and minimum trade count. Use this to find the best traders on Hyperliquid. Trade history is indexed from 2025-03-22 (pulse_global_stats.dataStartDate; see data_coverage for the current window).

Find the most dangerous markets: coins with the highest per-lifecycle liquidation rate. Returns coin, total lifecycles, liquidations, liquidation %, and total penalty. Use for 'which coins blow people up most often?'.

Look up one position lifecycle by its numeric ID, including the trade fills that composed it (timestamp, side, size, price, PnL, fee, tx hash) joined from the trades table within the open->close window. Use after pulse_trader_lifecycles to drill into exactly how a single position was built and unwound. Fills are paged by the connector: fillsLimit (default 100, max 1000) and fillsOffset; the response carries fillCount (total fills in the lifecycle), fillsOffset, truncated and a note with the next offset. Lifecycles are a rolling 90-day window (closed within the last 90 days, plus open ones); se…

Global feed of the most recently CLOSED position lifecycles across ALL wallets — 'what just closed exchange-wide right now'. Reads the corrected position_lifecycles_full table: includes MAE/MFE (when backfilled), a liquidation flag, and optional spot. Cross-wallet successor to pulse_recent_closed_positions. Filter by coin, minNotional, hold-duration range, and time window. Note: the very freshest closes may not have MAE/MFE yet — the risk backfill lags real-time, so recent rows can show null MAE/MFE. Lifecycles are a rolling 90-day window; the table's first day is not exposed by the API — see …

Power-law shape of trader profits: percentile bands (top 0.1%, 1%, 10%, ...) and each band's share of total profits. Returns band label, wallet count, band PnL, % of total profits, and rank range. Use for 'how concentrated is alpha — do the top 1% take everything?'.

Find the biggest survived drawdowns: closed perp positions that went deeply underwater (high MAE) yet still closed in profit. These are 'diamond hands' winners that nearly blew up first. Returns the position, entry/MAE/exit prices, realized PnL, and max drawdown %. Filtered to material positions (minPnl) with bounded drawdowns.

Get the most actively traded coins on Hyperliquid, ranked by trade count and volume. Use to understand what the market is focused on right now.

Show the current API key's plan: tier, rate limits (per-minute/daily/monthly), and every tier's limits. Use when the user asks what plan they are on or after a tier/rate-limit rejection. Live remaining-quota counts also arrive on every API response as X-RateLimit-* headers.

Find new big players: wallets whose first-ever lifecycle is recent but who have already moved large notional. Returns wallet, first-seen date, gross notional, total PnL, and lifecycle count. Use for 'who just showed up and is already trading big?'. Lower minNotional if no rows return at default.

Find flash-in-the-pan traders: big winners in a single month who then gave it back. Returns wallet, best-month PnL, total PnL, giveback amount, active months, and profitable months. Use for 'who had one great month then faded?'.

Find positions that exited near the top: closed perp positions whose exit captured a high fraction of the maximum favorable excursion (MFE). These are well-timed exits. Returns the position, entry/exit/MFE prices, realized PnL, and MFE capture % (capped at 100). Filtered to material positions (minPnl) with a real favorable move.

Find consistently profitable wallets: traders that were profitable in N+ distinct calendar months of the 90-day window. Returns wallet, profitable-month count, total PnL, and best-month PnL. Use for 'who is consistently good, not just lucky once?'.

Today's biggest realized winners AND losers: wallets ranked by summed realized PnL on positions CLOSED in the last 24h, with position counts and liquidation flags. Realized-on-the-day — different from the portfolio leaderboards (which rank account value over longer windows). Use for 'who made/lost the most money today?'. Requires Starter tier or higher.

Get recently closed positions across all traders. See what positions were just closed in the last N minutes/hours — with entry/exit prices and hold duration. Filterable by coin, minimum notional size, and hold duration range. Use to find: sub-second HFT trades (maxDuration=1000), positions that just got stopped out, large positions that just closed (minNotional=100000), quick scalps vs long holds.

Get the biggest trades on Hyperliquid in the last N minutes/hours. Returns trades sorted by absolute PnL — the largest movers. Use this to see what's happening right now on the exchange.

HFT vs swing vs holder PnL split, bucketed by lifecycle hold duration. Returns, per style bucket, lifecycle count, unique wallets, total PnL, avg PnL, and total fees. Use for 'do scalpers or swing traders make more money on Hyperliquid?'.

Find comeback traders: wallets whose cumulative realized PnL hit a deep trough and then climbed back to positive. Returns wallet, trough depth, current cumulative PnL, and recovery amount. Use for 'who blew up but recovered?'. Realized-PnL drawdown only.

Get the top traders for a specific coin. Answers questions like 'who are the best BTC traders?' or 'who profits most from SOL?'. Returns ranked traders with PnL, trade count, win rate, and volume for that specific coin.

Find wallets that profit by liquidating others' forced closes. Returns liquidator wallet, liquidations executed, distinct victims, distinct coins, total penalty collected, and total liquidation PnL. Use for 'who is the biggest backstop/liquidation player?'.

Get aggregate statistics about a trader's closed positions: average hold duration, win rate by position (not by fill), total positions closed, and PnL summary. Use this to understand how long a trader typically holds and their position-level performance. Answers: 'What is this trader's average hold time?', 'Win rate by position (not by fill)?', 'Is this trader a scalper or swing trader?', 'Average PnL per position?'

Get closed position history for any wallet. Shows every position that was opened and closed — with entry/exit prices, hold duration, PnL, and leverage. Use this to analyze a trader's position lifecycle and timing patterns. Answers: 'Show me all historical positions for this trader', 'What was the PnL and duration of each position?', 'When did this whale close their massive ETH long?'

Get day-by-day performance breakdown for any trader. Returns daily PnL, trade count, win rate, and volume for each day the trader was active. Use for deep due diligence and identifying consistency patterns.

Get a fast wallet briefing for demos and agent triage: lifecycle summary plus recent top wins and losses. Use when the user wants a quick read on a trader before deciding whether to run deeper lifecycle, drawdown, or token-level analysis.

Get a wallet's aggregate position-lifecycle stats: total/closed/open count, wins, losses, liquidations, win rate, total & avg PnL, biggest win/loss, avg/min/max hold duration, total fees, and unique coins traded. Same 90-day rolling window as pulse_trader_lifecycles. Use to size up a trader's position-level performance in one call.

Get a wallet's position lifecycle history — every open->close cycle reconstructed from on-chain fills, with entry/exit VWAP, peak size, hold duration, realized PnL, fees, fill count, and liquidation status. Richer than closed-positions: each row is a full position lifecycle. 90-day rolling window (closed within the last 90 days, plus open ones; the table's first day is not exposed by the API — see data_coverage); spot (@-prefixed) excluded by default. Use for deep position-level due diligence and timing analysis.

Get performance comparison for a trader: 30-day vs all-time PnL, trade count, win rate, and trend direction (improving/declining/stable). Use this to evaluate if a trader is currently hot or cooling off.

Get full profile for any Hyperliquid trader by wallet address. Returns total PnL, trade count, win rate, volume, largest win/loss, first/last trade dates, PnL tier, size tier, and profit factor. Use this for due diligence on any wallet.

Get token-by-token P&L breakdown for any trader. Shows which coins they trade, their PnL per coin, win rate per coin, and volume per coin. Use to understand a trader's edge — e.g. 'this trader only makes money on ETH and loses on everything else.'

Get recent trades for a specific wallet address. See exactly what a trader has been doing in the last minutes/hours — every buy, sell, size, price, and PnL. Essential for copy-trading and due diligence. Trade history is indexed from 2025-03-22 (pulse_global_stats.dataStartDate; see data_coverage for the current window).

Get a wallet's per-position drawdown (MAE) and run-up (MFE) curve: for each closed perp lifecycle, the worst adverse price excursion and best favorable excursion vs entry, as percentages. Use to judge a trader's pain tolerance and exit timing — 'how far underwater did they go before it worked?'. Perp-only (spot has no MAE).

Every builder (frontend, bot, HIP-3 dex) a wallet (0x-hex address) had attributed fills through within a lookback window (since, default '30d', clamped to 90d), ordered by builder fees paid descending. Each row: builder address, curated builderName (omitted when unknown), fills, builderFeesUsd, volumeUsd, and first/last attributed-fill timestamps within the window. Attribution slightly undercounts (trigger-order stop/TP fills not yet attributed — see the response's dataNotes). The inverse of builder_traders: wallet → builders instead of builder → wallets. Use for 'which apps does this trader u…