How to connect Coinversa Pulse MCP with Python

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 (from 2025-03-22); data_coverage reports the window and freshness of every dataset.

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. Call it only before relying on a historical date range or citing a start date, or when the user asks how fresh or complete the data is; do not call it as a first step or for live questions (prices, positioning, liquidation maps are already live). 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-derived, refreshed every 60 s, no history). Where the API exposes no window start the dataset is listed with windowStart null and a note; no date is guessed. Sources are queried sequentially (the API's per-key burst allowance is small) and a failing source is reported in that dataset's notes rather than failing the call. Also returns server { version, hiddenTools, toolCount }. Free tier (some sources need a higher tier and then report the tier gate in notes).

CANONICAL market discovery tool. Returns trading symbols 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. The full list is ~450 markets, so the connector trims it (the API route offers no paging): markets with no open interest and no 24h volume (hasActivity=false — delisted listings, including every market on the legacy flx/vntl/hyna/km/abcd/cash dexes) are hidden unless includeInactive=true, and rows are capped at `limit` (default 50, max 500) from `offset`. Rows keep the route's order (native perps first, then each builder dex, each in Hyperliquid listing order), so paging is stable. Narrow with `dex` or `search` (substring of the symbol, e.g. 'OIL' finds xyz:BRENTOIL) before raising limit. The response carries count (returned), totalCount (after filtering), inactiveHidden, truncated, hasMore and nextOffset (null on the last page — stop there) and a note naming the next offset. The io, mkts and para dexes are not served by this route yet (see the server instructions); asking for them returns an empty list with a note. globalStats: totalTrades24h is always 0 and totalUsers is capped at 1000 by the API — use pulse_global_stats / pulse_active_traders for those figures.

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'. The full directory is ~415 assets and far too large to return whole, so the connector trims it two ways (the API route offers neither): rows come back in `detail`='summary' form by default — identity, venue symbols and cross-venue totals, without each venue's price/funding/OI, which is what list_markets and pulse_cross_market_asset are for — and are capped at `limit` (default 25, max 500) from `offset`. The route returns the directory ordered by aggregate open interest, DESCENDING, and the connector preserves that order, so the default page is the 25 largest assets by open interest — not an arbitrary 25. The response carries count (returned), totalCount (after filtering), truncated, hasMore and nextOffset (null on the last page — stop there) and a note naming the next offset. Narrow with `search` (matches canonical name, synonyms and venue symbols) or `crossMarketOnly` before raising limit; pass detail='full' only when you actually need per-venue market data. To look up one asset you already know, use list_asset — it is one row and needs no paging.

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.

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

Ranked Hyperliquid trader leaderboard (best or worst). Supported sorts: PnL, fill win rate, volume, and losers. score and risk-adjusted are unavailable. minTrades is enforced before ranking for every supported sort and period. PnL is gross closed PnL before fees; winRate is positive-PnL fills divided by all fills (including zero-PnL opening fills), NOT position win rate. Trade rollups include spot and outcome fills, so this is not a perp-only ranking and spot sale PnL is not reliable cost-basis profit. day/week/month use UTC calendar-day aggregates, not exact rolling-hour windows. Trade history is indexed from 2025-03-22 (pulse_global_stats.dataStartDate; see data_coverage for the current window).

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.

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

Start here to profile, analyze or look up any Hyperliquid wallet (0x address) — call this first for 'profile/analyze this wallet' and due diligence. Returns the wallet's lifetime trading record from every indexed fill: total realised PnL, trade (fill) count and fill-level win rate, volume, fees, largest single-fill win/loss, first/last trade dates, all-time and 30-day PnL tier, size tier, and 30-day PnL. Fill counts are trades, not positions: for position-level wins/losses/liquidations add pulse_trader_demo. In clients that support interactive views this renders the Coinversa wallet card (90-day position stats, PnL curve, open positions).

Get performance comparison for a trader: 30-day vs all-time PnL, trade (fill) count, fill-level win rate, and trend direction (improving/declining/stable). Use this to evaluate if a trader is currently hot or cooling off. For a general wallet profile, call pulse_trader_profile first. In clients that support interactive views this renders the Coinversa wallet card (90-day position stats, PnL curve, open positions).

Current mark price of a crypto, commodity or stock perp on Hyperliquid. Use standard symbols (BTC, ETH, SOL) or builder dex format (xyz:SILVER, xyz:BRENTOIL, xyz:TSLA). io, mkts and para markets are not served yet.

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

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.

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

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

Liquidation map for a coin: at which prices open long and short positions would be liquidated. Returns the current price, total long and short notional at risk, and price buckets with positions, notional at risk and cumulative notional per side — use it to spot liquidation clusters and potential squeeze zones.

Exchange-wide view of crowding, leverage and liquidation risk right now. Get the exchange-wide market risk snapshot. Best for questions like 'what looks fragile right now?' or 'which coins are most crowded?'. Always returns the exchange totals — open interest, unique wallets, long/short counts, net bias, average leverage, unrealized PnL, top-10 crowding concentration and near-liquidation notional — plus availability/freshness stamps. The bulky parts are sections you opt into with `include`: topCrowdedCoins (default), longShort (per-coin long/short breakdown, ~25 rows), liquidationSummary7d (7-day totals plus byCoin and a daily timeline) and history (one open-interest row per market, ~325). The response lists sections and omittedSections. topCrowdedCoins, longShort.bySymbol, liquidationSummary7d.byCoin and history.oi are each capped at `limit` (default 10) with totalCount/truncated/hasMore/nextOffset on each list; page with offset (nextOffset null means that list is finished) or raise limit. For a coin-level view use live_coin_risk_snapshot; for time series use live_coin_risk_history.

How crowded and liquidation-prone one coin is right now. 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?'. Always returns the coin's concentration scalars — concentrationTop5, nearLiquidationNotional, nearLiquidationPositions, avgLiquidationDistancePct — plus availability/freshness stamps. Everything else is a section you opt into with `include`: market, longShort and topPositions are the default posture set; sizeBreakdown, liquidationHeatmap (40 buckets), liquidationSummary7d and recentLiquidations are opt-in. The response lists sections and omittedSections. topPositions is capped at `limit` (default 10, the API serves 20) with totalCount/truncated/hasMore/nextOffset; page with offset until nextOffset is null. For the heatmap alone use live_liquidation_heatmap; for liquidation events use live_recent_liquidations; for time series use live_coin_risk_history.

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 the complete minute-level series, or use live_mark_dislocations when you want explicit resolution and row-limit controls. The response lists sections and omittedSections. Freshness and availability are in the response's freshness/availability stamps; see data_coverage for the risk-data window.

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 days at full detail use resolution=1h, or page by shortening hours. See data_coverage for the risk-data freshness stamp.

Individual liquidation events over a recent window (default last 7 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.

How much got liquidated over a time window, in total and per coin. Aggregated liquidation summary — the best liquidation tool for summaries, rankings and trend analysis. Returns event count, liquidated notional (total and long vs short), wallets affected, penalty fees, closed PnL, per-coin and per-trader-tier rollups, and a liquidation timeline.

Are more traders long or short, for one coin or the whole exchange. Get long/short ratio data. With a coin, returns that pair's ratio plus its top 5 long and short positions. Without a coin, returns the exchange-wide totals plus a per-coin breakdown (bySymbol) — ~430 coins, so the connector caps it (the API route has no paging): bySymbol keeps the route's order, largest total notional (long + short) first, capped at `limit` (default 25, max 500) from `offset`, with count (returned), totalCount, truncated, hasMore and nextOffset (null on the last page — stop there) and a note naming the next offset. The global breakdown carries no per-coin top positions (the route never fills them), so those fields are dropped from bySymbol rows; call again with coin for them. With `hours`, returns the history series instead (oldest first, newest `limit` rows kept, `offset` pages further back).

Who is long or short a coin right now, split by how profitable the traders are. Returns, for each PnL tier (Apex, Sharps, Grinders, Scrapers, The Crowd, Bleeders, Trapped, Blown Out — emitted as legacy slugs money_printer…giga_rekt) on the given coin, long/short wallet counts and notional, net bias (by notional and by count) and a bias label. Answers questions like 'are the Sharps traders long or short ETH?'

Get day-by-day performance breakdown for any trader. Each row is one active day: date, pnl, trades, winningTrades, volume and cumulativePnl (the running total over the trader's whole history, so it stays correct on any page). Use for deep due diligence and identifying consistency patterns. A long-lived wallet has hundreds of active days, so the connector pages them (the API route returns every day at once with no paging): rows come back NEWEST FIRST in `days`, capped at `limit` (default 90, max 1000) from `offset`, with count (returned), totalCount (after filtering), truncated, hasMore and nextOffset (null on the last page — stop there) and a note naming the next offset. Narrow to a period with startDate/endDate (YYYY-MM-DD, inclusive) instead of paging when you know the window. Note: this returns an object ({ address, days, … }), not a bare array.

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.

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.

Answers: how deep and how lopsided is this book right now? Returns touch prices, spread in bps, and per side the size / order count / distinct wallet count within 0.5, 1, 2, 5 and 10 % of mid (nested bands, not rings), plus near- and far-band imbalance, the number of orders resting at the touch, their median age, and the share of them that are post-only. Example: 'is HYPE's bid side thinner than its ask side inside 1 %?' — book_summary('HYPE') and compare bid.bands vs ask.bands. Snapshot-derived: refreshed every 60 s, latest-only (no history), and `as_of_height` is the L1 block the answer is true at — check `age_s` before citing it. `market_orderbook` remains the aggregated L2 view; this is the L4 one. Coin is case-sensitive in the node's own spelling (BTC, xyz:GOLD, #28200) and is passed through unchanged — 'btc' will 404. Pro tier.

Answers: where are the stops, and how much size fires if price gets there? Buckets every untriggered stop / take-profit order by distance from mid in 0.25 % steps, out to `within_pct`, reporting per bucket the count, size, reduce-only share, stop vs take-profit split and side split — plus totals below and above mid, the nearest trigger each side, and how many sit beyond the window. Example: 'what is stacked under BTC within 2 %?' — book_stop_map('BTC', within_pct=2) and read totals_below plus the negative buckets. Note totals_below / totals_above / nearest_* always cover EVERY trigger on the coin, while `buckets` is the `within_pct` window. Snapshot-derived: refreshed every 60 s, latest-only (no history), and `as_of_height` is the L1 block the answer is true at — check `age_s` before citing it. `market_orderbook` remains the aggregated L2 view; this is the L4 one. Coin is case-sensitive in the node's own spelling (BTC, xyz:GOLD, #28200) and is passed through unchanged — 'btc' will 404. Pro tier.

Answers: who is sitting on this book, and where? Returns the largest resting orders (wallet, side, price, size, original size, distance from mid, tif, order type, how long it has rested) and the biggest wallets per side by total resting size. Example: 'is one wallet holding up the ETH bid?' — book_whales('ETH', limit=10) and check whether bid_wallets[0].size dominates. Wallet addresses join to the trader tools (pulse_trader_profile, pulse_trader_performance). Snapshot-derived: refreshed every 60 s, latest-only (no history), and `as_of_height` is the L1 block the answer is true at — check `age_s` before citing it. `market_orderbook` remains the aggregated L2 view; this is the L4 one. Coin is case-sensitive in the node's own spelling (BTC, xyz:GOLD, #28200) and is passed through unchanged — 'btc' will 404. Pro tier.

Answers: what does the depth ladder look like, with the detail L2 throws away? The top price levels per side, best-first, each with total size, order count, DISTINCT WALLET count and the age of the oldest order on it — so a level held by one wallet's single order is distinguishable from the same size spread across twenty. Example: 'is SOL's 3rd bid level real depth or one wallet?' — book_levels('SOL', depth=5) and read bids[2].wallets. Snapshot-derived: refreshed every 60 s, latest-only (no history), and `as_of_height` is the L1 block the answer is true at — check `age_s` before citing it. `market_orderbook` remains the aggregated L2 view; this is the L4 one. Coin is case-sensitive in the node's own spelling (BTC, xyz:GOLD, #28200) and is passed through unchanged — 'btc' will 404. Pro tier.

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.

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.' For a general wallet profile, start with pulse_trader_profile.

Get the most actively traded coins on Hyperliquid, ranked by cumulative trade count (descending). Each row: coin, traders (unique wallets), totalTrades and totalPnl. Note this route returns no volume figure — for traded volume use list_markets (24h volume per symbol) or pulse_exchange_volume. Use to understand what the market is focused on right now.

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 complete closed perp lifecycles for a wallet within the rolling lifecycle retention window (normally 90 days; see data_coverage). Excludes positions opened before reconstruction coverage. Uses the same source and completeness filters as pulse_trader_closed_position_stats, whose aggregate is capped at the latest 10,000 positions. Shows entry/exit VWAP, peak size, hold duration, gross realized PnL before fees, and lifecycle fees. leverage and leverageType are null because historical leverage is not tracked. This is not all-time position history.

Get aggregate statistics over the latest 10,000 complete closed perp lifecycles available for a wallet in the rolling lifecycle retention window (normally 90 days; see data_coverage), not all-time history. Same source and completeness filters as pulse_trader_closed_positions. Reports average hold duration, positive-PnL position win rate (not fill win rate), total positions and gross realized PnL before fees. Flat closes count as non-wins.

Get recently closed perp lifecycles across all traders, with entry/exit VWAP, peak size, hold duration, gross realized PnL before fees and lifecycle fees. leverage and leverageType are null (not tracked historically). Filter by coin, minimum peak notional and hold duration. Use to find sub-second HFT trades (maxDuration=1000), large positions that just closed (minNotional=100000), or quick scalps vs long holds.

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

Recent price chart data (1-minute candles, last 12 hours). 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.

Get historical hourly bias snapshots for trader cohorts. Returns long/short notional and account counts per tier. netBias is notional-weighted percent: 100 * (longNotional - shortNotional) / (longNotional + shortNotional), from -100 to +100 (zero for no notional), both per coin and in the global aggregate. Global bias is recomputed from summed notionals, not summed percentages. Filter with tierType and/or tier for a readable series. The default window is 7d. Returns { rows, totalCount, truncated, note? } with rows newest first, capped at limit (default 100, max 2000); when truncated, narrow filters or the time window. See data_coverage for the available history.

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 30 days; see data_coverage.

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.

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 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 — one row per tier per hour, so the 7-day default for all 8 tiers of a category is ~1,300 rows. Returns { rows, count, totalCount, truncated, hasMore, nextOffset, note? } with rows newest first (then tier), capped at `limit` (default 100, max 2000) from `offset`; nextOffset (and the note) name the next page, and are null / 'End of results' on the last one. Pass tier for a single series, or shorten hours, before raising limit.

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 API clamps every look-back to it) — see data_coverage for freshness.

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

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.

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. Questions are returned newest first (questionId descending) and capped at `limit` (default 25, max 200; the API route has no paging, so the cap is applied by the connector) from `offset` — the response carries count (returned), totalCount (after filtering), truncated, hasMore and nextOffset (null on the last page — stop there) and a note naming the next offset. Narrow with `status` (open = nothing settled yet, settled = at least one named outcome settled) or `search` (matches name, description and class). For one question's outcomes use hip4_outcomes; HIP-4 is indexed from mainnet launch (2026-05-02) — see data_coverage.

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

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.

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.

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.

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.

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. Each row: id, address, coin, side, entryVwap, exitVwap, peakSize, notional, realizedPnl, fees, builderFee, wasLiquidated, openedAt/closedAt (+ raw ms) and durationMs. MAE/MFE (maePx/mfePx) are returned only when non-zero, and they scale with position size: on an UNFILTERED call — which is newest-first and therefore dominated by dust-sized closes — no row carries them (sampled 0 of 200 at median notional ~$270). Pass minNotional to reach positions that have them: ~42% of rows at minNotional=10000, ~89% at minNotional=100000. Plan on filtering rather than on the fields being there. Cross-wallet successor to pulse_recent_closed_positions. Filter by coin, minNotional, hold-duration range, and time window. Ordered by close time descending and bounded by `since` (default 1h) and `limit` — this is a recency feed, NOT a 90-day window, and wide windows can time out; for a wallet's full 90-day history use pulse_trader_lifecycles. See data_coverage for the lifecycle freshness stamp.

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

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, hasMore and nextOffset (the next fillsOffset; null on the last page — stop there) and a note naming it. Lifecycles are a rolling 90-day window (closed within the last 90 days, plus open ones); see data_coverage.

Get a fast position-level wallet briefing: the 90-day position-lifecycle summary (closed/open positions, wins, losses, liquidations, realised PnL, biggest win/loss) plus recent top winning and losing positions. Pairs with pulse_trader_profile (call that first to profile or analyze a wallet); use this for position-level win/loss before deciding whether to run deeper lifecycle, drawdown, or token-level analysis. In clients that support interactive views this renders the Coinversa wallet card (90-day position stats, PnL curve, open positions).

Get a wallet's per-position drawdown (MAE) and run-up (MFE) timeline, NOT an account equity curve. For each closed perp lifecycle, reports direction-aware adverse and favorable price excursions vs entry as percentages, floored at zero when the position never moved adversely or favorably. Prices come from indexed lifecycle extrema, not a fresh candle reconstruction. Perp-only, within the rolling lifecycle retention window (normally 90 days; see data_coverage).

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 { events, count, hasMore, nextOffset, placeholderRowsSkipped, rowsScanned, note?, dataNotes? }: each event has the position, entry/MAE/exit prices, realized PnL, and max drawdown %, deepest drawdown first. Filtered to material positions (minPnl) with bounded drawdowns. Rows whose MAE price is a placeholder of exactly 1 on a market priced far from 1 (an upstream data defect that fakes a ~99.9% drawdown) are skipped and counted in placeholderRowsSkipped; paging (limit/offset) runs over the remaining events, and nextOffset is null on the last page.

Find closed perp positions whose exit captured a high fraction of the indexed maximum favorable excursion (MFE). Reports gross realized PnL before fees and direction-aware capture percent from entry/exit/MFE prices. Requires a favorable move of at least 1%; inconsistent rows whose exit exceeds indexed MFE are excluded, not clamped into perfect 100% exits. Indexed extrema may differ from a fresh candle reconstruction. Within the rolling lifecycle retention window (normally 90 days; see data_coverage).

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.

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.

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

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

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.

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

Find the wallets that execute the most liquidations (take over other traders' forced closes). Returns liquidator wallet, liquidations executed, distinct victims, distinct coins and total penalty collected. victimClosedPnl (and its older alias totalLiquidationPnl, same value) is the closed PnL of the positions that were liquidated — the VICTIMS' losses, which is why it is negative — NOT the liquidator's profit, which the data does not attribute. Use for 'who is the biggest backstop/liquidation player?'; do not report either PnL field as what a liquidator earned.

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

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

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.

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

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

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

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.

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.

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.

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.

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

Show the current API key's plan: tier, rate limits (per-minute/daily/monthly), and every tier's limits. Call ONLY when the user asks about their plan, tier or limits, or right after a request was rejected for tier or rate-limit reasons. Do not call it as a first step, to introduce the connector, or before answering a market question. Live remaining-quota counts also arrive on every API response as X-RateLimit-* headers.

Which master account a wallet belongs to, and the combined positions across all its sub-accounts. 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. For a wallet's own trading record, start with pulse_trader_profile. Requires Pro tier.

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.

24h trading volume for the WHOLE exchange, split by dex: native Hyperliquid ('hl') plus every builder dex (xyz, io, para, ...), with per-dex match counts and distinct traders. Use for 'how much volume does Hyperliquid do?' — and note builder dexes are a large share of it (~30% on 2026-09-23; read byDex for today's split rather than assuming). Aggregates cached up to 120s.

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.

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.

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.

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.

Builders (HIP-3 dexes, frontends, bots) ranked by exact revenue from Hyperliquid's on-chain cumulative builder-fee ledger over the requested period. Each row carries join-attributed fill volume, distinct users, and fill counts — plus the same metrics for the immediately preceding window for deltas — the builder's most common requested fee rate over the last 7d of orders (feeTenthsBp, tenths of a basis point), and builderName from a curated registry (omitted when unknown). Attributed metrics slightly undercount versus ledger revenue because trigger-order fills (stop/TP) are not yet attributed — see the response's dataNotes; the 'verified' stamp gives the ledger block this data was reconciled against. Use for 'which builders earn the most?' or 'is builder X growing?'. Ledger history begins at the fee ledger's first on-chain entry: dataNotes states that date whenever a window predates it, and data_coverage (builder_ledger) reports it. Requires Starter tier or higher.

Single-builder overview for a 0x-hex builder address: exact revenue from Hyperliquid's on-chain builder-fee ledger over the period (day/week/month), first/last fee accrual timestamps, distinct fee tokens, most common requested fee rate over the last 7d of orders (feeTenthsBp, tenths of a basis point), a daily attributed series (fees/volume/users/fills) with the biggest day highlighted, top coins by attributed volume, and how many of the period's attributed wallets are all-time profitable. Attributed metrics slightly undercount versus ledger revenue (trigger-order stop/TP fills not yet attributed — see the response's dataNotes); builderName comes from a curated registry, omitted when unknown. Returns 404 for addresses with no revenue in the fee ledger. Use for 'how is builder X doing?' or 'what do people trade on frontend Y?'. Requires Starter tier or higher. Availability: typically 10-25 seconds on large builders; the coin split (topCoins) may come back null with an explanation in dataNotes when the live pass exceeds its budget. Ledger history begins at the fee ledger's first on-chain entry (see data_coverage, builder_ledger).

Wallets that traded via a builder (0x-hex address) in the window, sortable by builder fees paid, volume, or realized PnL. Each row: wallet, realized PnL on its attributed fills, builderFeesUsd, volumeUsd, fills, latest equity (0 if untracked), and the wallet's ALL-TIME exchange-wide cohort tiers (pnlTier/sizeTier, emitted as legacy slugs like smart_money/whale; null if untracked) — lifetime labels, unlike the 30d-rolling tiers the pulse cohort tools classify by, so memberships can differ. Attributed fills slightly undercount versus ledger revenue (trigger-order stop/TP fills not yet attributed — see the response's dataNotes). Use for 'who are builder X's biggest fee payers?' or 'are smart-money wallets using this frontend?'. Requires Pro tier. Availability: this endpoint computes per builder on request and can exceed its 30-second budget on large builders; if it times out, retry once a minute later.

Individual fills attributed to a builder (0x-hex address) within a lookback window (since, e.g. '6h' or '7d', clamped to 90d), optionally filtered to one exact coin (BTC, xyz:GOLD, @123 spot, #10010 HIP-4 outcome) or one wallet. Each fill: time, wallet, coin, marketType (perp|spot|hip4), side (BUY|SELL), price, size, USD volume, realized PnL, builderFeeUsd, tid, and the order id it attributes to (null if untracked). Trigger-order (stop/TP) fills are not yet attributed, so this feed slightly undercounts versus ledger revenue — see the response's dataNotes. Use for 'show me the flow going through frontend X right now' or auditing one wallet's activity via a builder. Requires Pro tier.

Cohort composition of a builder's attributed users over the period (day/week/month): split by all-time exchange-wide profitability tier (pnlTiers) and size tier (sizeTiers), largest cohort first, each with users, share of totalUsers, builder fees paid, attributed volume, realized PnL, and fills. Tiers are LIFETIME labels emitted as legacy slugs (money_printer..giga_rekt / leviathan..shrimp) — not the 30d-rolling tiers the pulse cohort tools use — and wallets missing from the rollup appear under 'untracked' so per-tier user counts always sum to totalUsers. Attribution slightly undercounts versus ledger revenue (trigger-order fills — see the response's dataNotes). Use for 'is builder X's user base smart money or exit liquidity?' or 'do whales or shrimp pay most of its fees?'. Requires Pro tier. Availability: computed per builder on request and can exceed its 30-second budget on large builders; if it times out, retry once a minute later.

Monthly retention matrix for a builder's users (takes only the 0x-hex builder address — no other parameters): wallets are cohorted by the calendar month (YYYY-MM, UTC) of their first builder-fee order via this builder, and each cohort's activeWallets[k] counts wallets still active k months later, where 'active' = placed at least one builder-fee order that month (index 0 = the cohort month itself = newWallets). Covers the last 12 calendar months, oldest cohort first. Measured on the ORDERS plane — the order need not fill — so counts can exceed the attributed-fill user counts on builder_cohorts/builder_overlap; see the response's dataNotes for the attribution caveat. Use for 'does builder X retain users month over month, or churn them?'. Requires Pro tier.

The top 10 OTHER builders this builder's active users also traded through in the period (day/week/month), ranked by shared users — i.e. which other frontends/bots/dexes this builder's audience also uses. Returns activeUsers (the share denominator: distinct wallets with attributed fills via this builder) and per row: the other builder's 0x address, curated builderName (omitted when unknown), sharedUsers, share of this builder's active users, and feesUsd those shared users paid to the OTHER builder in the period. Based on attributed fills, which slightly undercount (trigger-order fills — see the response's dataNotes). Use for 'who is builder X's closest competitor?' or 'where else does its audience trade?'. Requires Pro tier.

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 use?' or 'how much has wallet X paid frontend Y in fees?'. For a general wallet profile, start with pulse_trader_profile. Requires Starter tier or higher.

How fast and how unevenly a builder monetizes the wallets it acquires (takes only the 0x-hex builder address — no other parameters): users and minFills, avgRevenueUsd and medianRevenueUsd of lifetime attributed builder fees per qualifying wallet, concentration (avg/median — 1 = evenly spread, higher = whale-skewed, 0 when the median is 0), daysToPeak, daysToHalfRevenue and daysToThreeQuartersRevenue as {avgDays, medianDays} measured from each wallet's first attributed fill to its single highest-revenue day and to 50% and 75% of its lifetime fees, and peakDayDistribution bucketing those wallets into under7d, from7To30d and over30d. NOT the lifetime user base builder_lifecycle covers: the universe is the TRAILING-YEAR acquisition cohort — wallets whose first builder-fee order via this builder fell within the last 365 days, with at least minFills (fixed at 3) lifetime attributed fills — computed per wallet then aggregated, so young cohorts' truncated series bias the day counts low; see the response's dataNotes. Use for 'how fast and how unevenly does builder X monetize a new user?'. Requires Pro tier.

Where every wallet that ever traded via this builder stands today (takes only the 0x-hex builder address — no other parameters): totalUsers split into five MUTUALLY EXCLUSIVE statuses that sum back to it, each {users, share} — active (attributed fill via THIS builder within 7d), cooling (within 30d but not 7d), switched (no fill here in 30d but at least one via a DIFFERENT builder in that window, detectable only with all-builder attribution), dormant (no fill via any builder in 30d, last fill here within 90d) and movedOn (no fill anywhere in 30d and none here in 90d) — plus trueRetention ((active+cooling)/totalUsers), churn ((dormant+movedOn)/totalUsers) and competitiveLoss (switched/totalUsers), which sum to 1, and competitiveLossFeesUsd, the builder fees those switched wallets paid to OTHER builders in the last 30d. LIFETIME universe on the ORDERS plane — every wallet that ever placed a builder-fee order via this builder, including ones whose orders never filled (they land in movedOn, or in switched if they filled via a DIFFERENT builder in the last 30d) — with only the status test reading recent attributed fills, so this is one snapshot of the whole historical user base rather than builder_retention's per-cohort monthly grid; see the response's dataNotes. Use for 'how many of builder X's users are still active, and how many did a rival take?'. Requires Pro tier. Availability: typically 1-15 seconds; can exceed its 30-second budget on the largest builders, in which case retry once a minute later.

What this builder's users INTEND at placement time, before anything fills (0x-hex builder address plus a day/week/month period): totalIntents — non-trigger order intents plus still-PENDING stop/TP placements, the actions denominator — an actions[] mix of {actionType, orders, share}, largest first except the 'trigger' pseudo-type which is appended last, over 'order' (plain placements), 'batchModify' (modify intents on an existing order) and 'trigger' (pending stop/TP placements), a tifs[] time-in-force mix of {tif, orders, share} over non-trigger intents ('unknown' covers market orders and older rows), reduceOnlyShare, a trigger breakdown (total, takeProfit, stopLoss, triggerMarket, triggerLimit, positionTpsl, standaloneTpsl, resolved, pending) and fillConversion {orders, filledOrders, share} — the share of non-trigger intents whose own oid took at least one attributed fill. Measured on the PLACEMENT plane, not the fill plane behind builder_fills and builder_traders, so orders that never filled still count; trigger placement history begins 2026-03-24, and a resolved placement is excluded from totalIntents and the 'trigger' action because it already surfaces as a plain 'order' row, while the trigger breakdown covers both statuses — see the response's dataNotes. Use for 'do builder X's users place stops and take-profits, and how much of their order flow actually fills?'. Requires Pro tier.