WebSocket
Derived quotes: bbo, l2Book and allMids
Three feeds now publish a derived view of the same resting book l4Book is
built from, instead of the raw orders. Two of them are on every plan.The catalog is twenty-four feeds, up from twenty-one.
bbo sends a message only when the top of book changes. l2Book and allMids
each replace their whole view on every frame — the top-20 depth and the
entire mids map respectively — so neither is a diff stream, and applying them
as diffs corrupts the result.allMids is an initial version and is narrower than Hyperliquid’s own: it
covers native perpetual markets only, with no spot, no builder dexes and no
fall back to the last trade when a book side is empty. A coin missing either
side is omitted from the map, so absence means one-sided, not zero.All three share one book per coin. The subscribe is acked at once; what
waits is the first data frame, while the server re-requests the snapshot every
250 ms behind that ack. If the book is not ready in 2 minutes (bbo,
l2Book) or 5 minutes (allMids), quote book warming up arrives instead
of the snapshot. Do not time out waiting for the first frame sooner than that. seq is the source book
height and skips blocks that changed nothing visible.MCP
Connector v0.13.0: payload controls on the five heaviest tools
live_risk_overview, live_coin_risk_snapshot, list_assets, hip4_questions
and pulse_trader_daily_stats returned payloads with no way to trim them. All
five now take shaping parameters — include, search, detail, status,
startDate/endDate, and limit/offset as each one warrants — and every
capped response carries totalCount, truncated and a note naming the next
offset.These are applied by the connector, after it fetches the endpoint. The API
routes take none of them: /live/risk/overview and /hip4/questions accept no
query parameters at all, /live/risk/coins/{coin} and
/pulse/trader/{address}/daily accept only their path parameter, and /assets
accepts only crossMarketOnly. A route ignores a parameter it does not
declare, so GET /assets?limit=3 still returns all 415 assets. See
Connector-side parameters.The catalog page also now lists builder_lifecycle, builder_journey and
builder_orders (shipped in 0.11.1 but never added) and drops
pulse_market_overview, removed in 0.12.0. builder_heatmap is registered but
withheld while its hourly rollup backfills, so the connector advertises 106
of its 107 tools.WebSocket
TWAP statuses: the node’s own state machine, with a live-set snapshot
Two new Pro feeds close the last gap in the TWAP product.twapStatuses and
twapStatusesByUser carry the node’s own TWAP state machine — activated,
waiting on a trigger, finished, terminated, stopped, or refused mid-run — and a
subscription opens with a snapshot of the TWAPs running right now. The
catalog is twenty-one feeds, up from nineteen.twap_id:Two things to know before building on it. The snapshot reports its own coverage:
complete says whether the upstream reaches back far enough to hold every
activated TWAP, and coverage_from_ms is the oldest block time it has applied —
when complete is false, a TWAP that activated before that bound may be
missing from the set, so apply the stream on top of the snapshot and insert a
twap_id you had not seen rather than discarding the event. And twapStatuses
sequences on the source block height, while its sibling twapOrders
sequences on a nanosecond replica timestamp: the two views join on
twap_id, never on seq, and one cursor cannot span them.There is deliberately no twapStatusesByUsers — this is the one
wallet-scoped family with no multi-wallet list variant. Follow a set of accounts
by filtering the unfiltered feed on state.user.Full contract in TWAP statuses; the snapshot
and error frames are on the wire protocol
page.WebSocket
Multi-wallet feeds: 1,000 addresses on one subscription
Every by-user websocket feed now has a list variant that follows a set of wallets on a single subscription. The catalog is nineteen feeds, up from fourteen.Each carries exactly what its singular feed carries — the same
[wallet, fill]
pairs, liquidation objects or replica updates, under the same seq — filtered
to any wallet in the list. The wallets go in a required users JSON string
array:APIMCP
L4 order book: four tools, four routes, and the wallet on every order
Four question-shaped views over the order-level book — every resting order with the wallet behind it, not an aggregated ladder. Each answers one question rather than handing you a book to parse:All four are Pro.
/market/book/coverage is Free and reports coins covered,
the latest L1 height and how fresh it is.The wallets join to the trader tools. book_whales returns addresses that go
straight into pulse_trader_profile — so “who is holding up this bid, and are
they any good” is one follow-up call. That join is the reason these exist as
question-shaped views rather than a raw book dump.Snapshot-derived and latest-only: one row per coin, replaced when its block
height advances, so there is no history. Every response carries as_of_height
and age_s — check age_s before citing a number, and past the staleness
ceiling the routes answer 503 rather than serving a stale book. data_coverage
gains a book dataset. For the aggregated L2 view with no tier gate,
market_orderbook is unchanged.Full contract: MCP tools and
tier matrix.Connector v0.12.0 is published — npx @coinversaa/mcp-server now carries
these four tools, taking the catalog to 107. It also picks up two data_coverage
fixes that shipped between releases: source calls are now sequential and paced
250 ms apart, with 429 backoff, so a coverage call no longer burns a key’s burst
allowance. Anyone pinned to 0.11.1 has been hitting the old behaviour.API
Five new feeds: allCandles and TWAP
allCandles streams the same OHLC candles as candle
for every market at once on one subscription — interval and an optional
source, no coin. Starter and above.twapSliceFills and twapSliceFillsByUser carry every fill the node
attributes to a TWAP order, as the node’s own [wallet, fill] pairs — so a
client that already reads trades reads these unchanged. Group by twapId to
follow one order and sum sz to track its executed size. Starter for the
unfiltered feed, every plan for the by-user one.twapOrders and twapOrdersByUser carry TWAP placements, refusals and
cancellations. Refusals are emitted rather than dropped, because a refused
TWAP leaves no other trace anywhere on the network — filter on update_type if
you only want orders that ran. Pro and above.twap_id is the join key between the two: one gives an order’s terms, the other
its executions. Subscribe to both for a wallet and join on it.Also on candle: a closed candle is now republished once with "closed": true
(an omitempty addition, so nothing that ignores it is affected). Without it the
newest candle had to be treated as open indefinitely. Hyperliquid’s own channel
has no such flag, so this is an addition rather than parity.And for the record, since it reads like a bug and is not: 1M is thirty days,
not a calendar month, and 1w opens on a Thursday. Every interval is a
flat bucket floored against the Unix epoch. That is measured against
api.hyperliquid.xyz, where every observed 1M bucket is exactly 30 days wide
— keeping 30 days is matching Hyperliquid.API
candle — live OHLC on every plan
candle streams live OHLC candles for one market on one of 14 intervals
(1m … 1M). It is the first new websocket feed since launch that is not
Pro-gated: it is on every plan, Free included.o/h/l/c
are traded prices, v is traded base volume and n is the trade count, the
same meanings Hyperliquid’s own candle channel carries. Both sides of a trade
arrive as separate fills under one tid, and volume is counted once per tid
rather than once per fill, so v matches Hyperliquid instead of doubling it.
Trade candles sequence on the source block height, like the fill and book feeds.The previous mark-price behaviour is still available, now opt-in as
"source":"mark". It is byte-for-byte what it was. source defaults to
trade before the subscription id is hashed, so an omitted source and an
explicit "trade" are one subscription, not two.interval is case-sensitive and it bites: 1m is one minute, 1M is 30 days,
and both are valid, so an upper-cased argument subscribes successfully to the
wrong interval. coin is not case-sensitive here — btc and BTC are one
subscription — and s echoes the market as the data spells it. A value outside the allowed set
is refused in band with a new exact error string, invalid argument <arg> —
invalid argument interval and invalid argument source. Full contract:
candles.API
Four new websocket feeds: liquidations and leverage
liquidations and liquidationsByUser stream every liquidation on
Hyperliquid as it lands — the liquidated account, the counterparty that took
the other side, the coin, the penalty fee and the realized loss. Filtered out
of the same fill stream, so they carry the source block height as seq like
every trade feed.leverageUpdates and leverageUpdatesByUser stream accepted leverage
and isolated-margin changes read from the node’s replica-command stream —
leverage, isolated_margin and top_up_isolated_margin, with the account
each one applied to. Rejected actions never appear: every request is paired
with its accepted response by bundle hash and action index before anything is
published as an applied change, and user comes from the response rather than
the broadcaster, so an agent-signed action reaches the account it applied to.APIBreaking
seq is now the source block height
Check that seq increases, not that it increases by one. A filtered feed
sends no frame for a block that matched nothing, so tradesByCoin on a quiet
coin legitimately skips hundreds of numbers between frames. What is actually
broken is seq going backwards or repeating — the chain only moves forward,
so that means frames were replayed or reordered.On l4Book the snapshot now carries seq equal to its height (it was 0),
and every update carries seq == height. The replay-bridge frames that used
to arrive with seq: 0 are gone. Keep gating the book on prev: it names the
exact predecessor block, which seq alone does not.New: resume instead of starting over. Pass the last seq you applied back
on resubscribe and the server replays what you missed, with no snapshot:sequence is not retained or sequence is older than retained history, and should subscribe without the cursor. sequence and
snapshot are control data — they do not change the subscription id, so a
resume continues the same subscription. To skip initial state entirely, pass
"snapshot": false.Also changed: the 8-concurrent-l4Book-subscriptions limit is gone — book
subscriptions count against the per-connection cap like any other. Book
failures no longer arrive as {"channel":"l4Book","error":…,"reason":…}; they
are dropped and reported on the ordinary error channel, without the coin on
them.Expect a slower first book frame. The server now buffers about 105 source
blocks before it fetches the snapshot, so it has history to join the snapshot
onto. A cold subscription commonly waits 10–60 seconds, up to about 100 if
all ten attempts are needed — but only on a coin nobody else is subscribed to:
a warm feed group passes straight through. Two new errors end the wait,
snapshot buffer did not fill and snapshot is older than retained history.
The 30 MB message requirement for BTC is unchanged.See sequence numbers,
reconnecting and
Order book (L4).API
The full L4 order book, with wallets, on the WebSocket
A new feed,l4Book, streams the complete order book of one
Hyperliquid market — every resting order with the wallet behind it, plus
the untriggered stop and take-profit orders — straight from the node, as
one snapshot followed by a diff message per block (Hyperliquid’s own
public l2Book aggregates by price level; this is the order-level book,
with the trader on every order). Any market the node knows, spelled as the
node spells it: BTC, xyz:GOLD, #28200. The server holds no book; you
apply the diffs, and the wire gives you what you need to do it safely —
height and prev chain every block, empty blocks are still sent so
silence is detectable, and a partial flag marks a block the node only
half delivered. The client rule is one line: apply an update only if its
prev is the last height you applied; otherwise reconnect with the last
seq you applied, falling back to a fresh snapshot if that cursor is no
longer retained.Pro and above, and listed in the connected frame’s limits.feeds
when your account has it. Two things to size for: the snapshot is the
whole book in one message — about 30 MB for BTC, a few KB for most
coins — so set your client’s read limit, and book subscriptions count
against your connection’s subscription cap like any other.
Read the feed page at Order book (L4), copy an
order-book client in Browser, Node,
Python or Go, and see the plan limits for how
snapshots count against fair use.API
Browsers can connect to the WebSocket directly
A browserWebSocket cannot set headers, so until now no page could
authenticate to wss://ws.coinversa.ai. The connection manager now also
takes the key as the second subprotocol after the literal bearer —
new WebSocket(url, ['bearer', key]) — so a dashboard or tool of your own
can stream fills with no relay. The key still travels in a request header,
never in the URL, and the Authorization header keeps working unchanged
for every other client. A browser cannot read the HTTP status of a refused
upgrade, so on this path the three refusals arrive as close codes
instead: 4401 invalid or missing key, 4429 connection cap full, 4503
entitlement lookup unavailable. Details in
WebSocket authentication.The portal’s Usage page now shows websocket usage honestly: bytes delivered
against the fair-use allowance, frames and connections opened for the
period, and connections and subscriptions open against the account’s
resolved caps — enterprise overrides included — updated every minute.API
The WebSocket API is live
Every fill on Hyperliquid — native perps, the seven builder dexes, spot — streamed over one socket at block cadence, with the trader’s wallet on every fill andclosedPnl, dir and startPosition already attached. Three feeds:
trades (the firehose, Starter and above), tradesByCoin and
tradesByUser (every plan; tradesByUser takes any address, not
only wallets you control). Frame shapes are Hyperliquid-compatible, so
existing client code is familiar, and every data frame carries a
per-subscription seq so you can tell what you missed.Authentication is your existing API key, sent as Authorization: Bearer
on the HTTP upgrade — there is no separate websocket key and no auth frame.
Limits are on capacity, not messages: connections per account (shared
across your keys), subscriptions per connection, and a fair-use bandwidth
allowance; streaming never draws down your REST quota. Start at the
WebSocket overview, copy a
working client, and read the
plan limits.API
Builder analytics arrives on MCP (connector v0.11.0)
The eight builder-analytics endpoints are now first-class MCP tools on both the hosted connector (https://mcp.coinversa.ai/mcp) and the npx package
(@coinversaa/mcp-server@0.11.0), taking the tool surface from 91 → 99:
builder_leaderboard, builder_profile, builder_traders, builder_fills,
builder_cohorts, builder_retention, builder_overlap, and the inverse
trader_builders. Ask your agent “which frontends do MetaMask’s traders
also use?” and it can answer from cross-builder attribution no other data
source has. Full catalog in MCP tools; endpoint semantics in
Builder codes & attribution.Builder analytics: ledger-exact revenue for every builder code
Eight new REST endpoints cover the Hyperliquid builder-code economy — the fees that front-ends, wallet apps, bots, and builder dexes earn on the order flow they route. Revenue is computed from Hyperliquid’s own on-chain cumulative builder-fee ledger (validated to ±0.1% against the chain); fill-level detail comes from order→fill attribution. See the new Builder codes & attribution concept page and the endpoint guide.Starter:GET /builders/leaderboard— every builder ranked by exact ledger revenue, with attributed volume/users/fills and prior-period deltas.GET /builders/{builder}/profile— one builder in depth: revenue, daily series, top coins, user base, fee rate, first/last seen.GET /trader/{address}/builders— which builders a wallet trades through, ordered by fees paid.
GET /builders/{builder}/traders— the builder’s users with PnL, fees paid, equity, and cohort tiers.GET /builders/{builder}/fills— the raw attributed fill stream (perp / spot / HIP-4), filterable by coin and wallet.GET /builders/{builder}/cohorts— who actually uses the builder: user composition by PnL and size tier.GET /builders/{builder}/retention— a 12-month monthly retention triangle of first-order cohorts.GET /builders/{builder}/overlap— the top 10 other builders a builder’s users also trade through (cross-builder switching — only possible with all-builder attribution).
verified stamp (the ledger block and chain
time it was checked against) and a dataNotes disclosure. Attributed
history is complete since 2025-01-25 (most trackers’ builder data
starts around August 2025). Honest caveat: trigger-order (stop/TP) fills
currently attribute at ledger level only — per-builder attribution coverage
is ~77–95% while the backfill completes (live capture since 2026-08-20,
backfilled to 2026-03-24) — so attributed fills/volume/users slightly
undercount versus the exact ledger revenue; every response says so in
dataNotes.All 8 endpoints also ship x402 pay-per-call
twins — the first x402 surface in the docs (every GET endpoint has carried
a keyless /x402 twin since May 2026; builder analytics is where we make it
official): no API key, price quoted in the 402 challenge.In review: order-level lifecycle/journey/heatmap endpoints, weekly and
revenue-weighted retention, and a live attribution-coverage ratio in the
verified stamp. Builder MCP tools are also on the way.API
Cohort tiers renamed
The trader cohort tiers have new display names and new canonical input slugs. The new slugs are rolling out with this release everywhere a tier is an input — path parameters, query parameters, and MCP tool arguments. Until the rollout reaches your endpoint (and until your MCP connector refreshes its cached tool schemas, which may still list only the legacy slugs), keep sending legacy slugs if a new slug is rejected. Nothing breaks either way: legacy slugs remain accepted on input indefinitely, and responses are unchanged — they continue to return the legacy slugs (e.g.pnlTier still returns
money_printer).See Trader cohorts for the full tier reference.
API
Liquidation intelligence: notional, sides, and cohorts
The liquidation summary (GET /live/risk/liquidations/summary) now returns
the full two-layer picture:totalNotional— liquidated position value (the industry-standard headline number), alongside the existingtotalClosedPnlrealized losses.longNotional/shortNotionaland event counts — which side got force-closed.byCohort— liquidated notional, losses, events, and wallets broken down by behavioral tier. See who actually gets liquidated.wallets— distinct liquidated wallets in the window.
API
The Daily Pulse — frozen daily editions via the API
Two new FREE-tier endpoints expose The Daily Pulse, the auto-generated Hyperliquid morning edition:GET /pulse/daily/{date}— the edition for a givenYYYY-MM-DDdate. Editions are frozen: once stamped (00:05 UTC), the document never changes, so any past date returns exactly what it returned on day one.GET /pulse/daily/latest— the newest edition.
attributedPnl, attributedFee, attributedSize,
rawClosedPnl, fillPnlBasis), and cohort bias responses include
netBiasByCount / netBiasByNotional.Security
Zero-knowledge connector: your API key never leaves our backend
The hosted MCP connector’s credential handling has been rebuilt end to end:- Connecting no longer transmits your API key. Picking a key on the authorization page hands over a single-use connect code (2-minute lifetime, dead after first redemption). The MCP server exchanges it server-to-server for an opaque key reference — the raw key never touches the browser or the connector host.
- Pick any existing key. The authorization page now lists your active keys — connect one in a click, no need to have the value saved and no forced duplicate keys.
- Encryption at rest for everything else. Sessions from the paste-a-key flow are now AES-256-GCM-encrypted under a key held outside the database, and all OAuth bearer tokens are stored as SHA-256 digests. A stolen copy of the connector’s database yields nothing.
- Tiers, rate limits, metering, and instant revocation behave exactly as before — revoking a key still disconnects every agent authorized with it.
Connector
One-click connect: OAuth sign-up on the hosted MCP
Connecting Coinversa to Claude, Perplexity, Cursor, or any MCP client no longer requires copying an API key. Pastehttps://mcp.coinversa.ai/mcp
into your client and it opens the new authorization page:- Existing users sign in with their Coinversa account and connect a key
in one click — or paste a saved
cvsa_key directly. - New users create an account right on the page. Every new account gets 14 days of Pro — all 99 tools, no credit card — and the key is provisioned automatically.
- Keys stay visible once at creation and revocable any time from the developer portal; revoking a key disconnects every agent authorized with it.
v0.9.0
Entity resolution, tier-aware sessions & exchange aggregates
Pulse 0.9.0 adds owner-level intelligence: Hyperliquid traders run named sub-accounts that trade independently, so per-wallet views undercount every multi-account trader. Pulse now resolves any wallet to its owner entity and aggregates across the whole family — a view no other Hyperliquid data product offers. Under the hood, the position dataset is now reconciled hourly against Hyperliquid’s own chain state (the census pipeline), and responses carry the chain block they were last verified against.New features
- Entity resolution —
GET /entity/{address}resolves any wallet (master, sub-account, or unknown) to its owner entity: master address, every named sub-account, each member’s open book, the combined positions across all of them, and a verified-vs-chain stamp.GET /entities/leaderboardranks the top owners (not wallets) by combined open notional. Both Pro tier. MCP:pulse_entity_profile,pulse_entity_leaderboard. - Exchange aggregates —
GET /exchange/volume(24h volume by dex — builder dexes are ~43% of Hyperliquid volume and most trackers’ headline numbers omit them),GET /exchange/oi(open interest by dex with long/short split),GET /exchange/active-traders(24h distinct traders). MCP:pulse_exchange_volume,pulse_exchange_oi,pulse_active_traders. - Plan introspection —
GET /planreturns the caller’s tier, effective limits, and every tier’s limits with an upgrade link. MCP:pulse_my_plan. - Chain-verification stamp —
GET /census/stampexposes the chain-state block the dataset was last reconciled against; entity responses include it inline.
Updates
- Tier-gated and rate-limited responses are now machine-actionable: 403s
carry
current_tier,required_tier, and anupgrade_url(codeTIER_GATE), so agents can explain exactly what a request needs instead of a bare “forbidden”. - The MCP tool surface grew from 83 → 91 tools; the REST API from 87 → 96 endpoints.
- Data-accuracy note: this release follows a full reconciliation of the position dataset against Hyperliquid chain state — open positions, open interest, and volumes now match independent trackers to well under 1%, with the residual continuously verified.
v0.8.0
Position lifecycles & execution quality
Pulse 0.8.0 is built on a fully re-derived position-lifecycle dataset — every position reconstructed open→close from on-chain fills, now carrying MAE/MFE (the worst adverse and best favorable price each position ever saw). For the first time you can analyze execution quality, not just realized PnL.New features
- Position lifecycles — per-wallet open→close history, aggregate lifecycle stats, single-lifecycle drill-downs (with composing fills), and a one-call wallet briefing. See Position lifecycles.
- Execution quality (MAE/MFE) — per-position drawdown / run-up curves, “max-pain” survivors (winners that endured deep drawdowns), perfect exits (high MFE capture), and the most catastrophic individual liquidations.
- Trader archetypes — survivors & anti-survivors, persistent winners, capital-efficient titans (PnL per fee), one-month wonders, newcomer whales, coin kings, top liquidators, and lethal coins — all derived from 90-day lifecycle behavior.
- Market structure — per-coin winner/loser profit pools, profitability by UTC hour, alpha concentration (percentile profit share), HFT-vs-swing-vs-holder splits, and head-to-head wallet comparison.
- Refreshed cohorts —
pulse_cohort_recent_*tools label wallets by their last-30-day tier (not all-time), surfacing who is printing right now. - Global recent feed —
pulse_lifecycles_recentstreams the most recently closed positions across the entire exchange.
Updates
- The Pulse MCP tool surface grew from 55 → 91 tools — see the full catalog in MCP tools. The REST API now exposes 96 endpoints.
- The legacy closed-position tools (
pulse_trader_closed_positions,pulse_trader_closed_position_stats,pulse_recent_closed_positions) are kept for backward compatibility but are superseded by the lifecycle tools, which read the corrected lifecycle dataset (more history, MAE/MFE, spot coverage).
Notes
- MAE/MFE is perp-only (spot positions have no adverse/favorable excursion by design). The freshest closes may briefly show null MAE/MFE while the hourly risk backfill catches up.
v0.7.0
HIP-4 outcome intelligence
Coinversa Pulse now indexes the full HIP-4 outcome-contract wire format from Hyperliquid, with discovery, settlement, volume, recent trades, trader overlap, and perp-position context for every outcome.New features
- 12 HIP-4 MCP tools for outcome-contract discovery, settlements, volume, recent trades, and trader overlap. See the full surface in MCP tools.
- Outcome + perp context tool lets agents pull a trader’s open perp position alongside their HIP-4 outcome exposure in a single call — useful for hedging and conviction-overlap analysis.
- Hosted Remote MCP is now documented at
https://mcp.coinversa.ai/mcp, so you can connect agents without installing the npm package. See MCP setup.
Updates
- The Pulse MCP tool surface grew from 43 → 55 tools.
- README, agent SKILL metadata, and server instructions updated for the new HIP-4 surface.
Breaking changes
- Keyless / no-API-key mode has been removed. All MCP tools now require a Coinversa API key. Grab a free-tier key from the dashboard — see Authentication and Pricing for details.

