Skip to main content
Six event types, four cohort bias types and four liquidation risk types. Five of the event types deliver the frames of the WebSocket feed of the same name; priceCross synthesises its own. The four cohort bias types report a trader cohort’s positioning from stored snapshots and have a page of their own. The four liquidation risk types report potential liquidation exposure — one wallet’s positions, or a whole market — from stored positions, and have a page of their own too. The machine-readable version of this page is GET /v1/subscriptions/definitions: it lists the types your plan may create, each with its args, filters and minTier, and the same declarations drive validation — so read the endpoint rather than keeping a client-side copy (reference). Delivery examples are illustrative: addresses, hashes and amounts are made up.

The delivered frame

Every delivery is one POST whose body is the raw source frame plus the subscription it matched: On the six event types the objects inside data are exactly what the node emits, in the shape the WebSocket feed documents: [wallet, fill] pairs on the trade and TWAP-fill types (the fill object), liquidation objects on liquidations and liquidationsByUser (liquidations), TWAP status records on twapStatusesByUser (TWAP statuses), and crossing events on priceCross (below). Numbers keep the type and precision the node sent — sizes and prices are decimal strings. On the cohort bias types data holds cohort rows from a stored snapshot. On the liquidation risk types it holds a wallet’s positions or a market’s exposure, built from stored positions (delivered fields).

Filters

A filter is a field name with either an exact value or, for numeric fields, a bounds object:
  • All fields and all bounds combine with AND, per event.
  • Numeric values — exact ones too — are decimal strings compared with exact decimal arithmetic, never floating point. An optional minus sign and a decimal fraction are accepted; exponent notation, NaN, infinity and fractions like 1/2 are rejected. Maximum length 128 characters.
  • The numeric operators are gt, gte, lt and lte. There is no eq (use an exact value), no dollar sign, no expression tree and no arbitrary document path.
  • Exact text matching is case-sensitive: BTC differs from btc.
  • A missing, null, malformed or non-numeric value in the event does not satisfy a numeric filter.
  • Invalid fields, operators or values and impossible ranges return 400 before anything is saved. {"gt": "10", "lt": "5"} is impossible; equal endpoints are allowed only when both are inclusive ({"gte": "10", "lte": "10"}).
  • No filters (or {}) means no extra predicates.
Units are the market’s base size and quote price. quote means the market’s quote denomination — not a promise of USD conversion — so there is no dollar-notional filter. The cohort bias types have numeric filters of their own — netBias, longNotional, shortNotional and accountCount — under the same rules (cohort bias filters). Of the liquidation risk types only liquidationRisk takes a filter, liquidationDistancePct (liquidation risk filters).

One wallet or many

On the four by-user types — tradesByUser, twapSliceFillsByUser, twapStatusesByUser and liquidationsByUser — args.user is either one address string or an array of 1 to 1,000 addresses. The definitions advertise this on the argument itself: "user": {"type": "address", "required": true, "minItems": 1, "maxItems": 1000}.
Create
  • One array is one subscription against your allowance, not one per wallet, and one underlying processor feed. It does not change the type’s minimum plan.
  • Addresses are lowercased; an array is sorted and deduplicated. The 1,000 limit is checked before deduplication.
  • An empty array, an invalid address or more than 1,000 entries is a 400. A creation body over 64 KiB is refused.
  • In the response, a one-element array — including one left after deduplication — comes back as a string; the legacy top-level user field appears only for a single-wallet scope.
  • Matching events from every listed wallet in a source block arrive together, in source order, in one delivery’s data; the same filters apply to each event. The frame shape and the type’s channel do not change, and each [wallet, fill] pair names its wallet.
  • Non-wallet arguments (coin, threshold, source, direction) stay single-valued.
  • The two wallet liquidation risk types, liquidationRiskCross and liquidationRisk, are not among the four: their user is exactly one wallet, and the definitions advertise maxItems: 1 on it.

tradesByUser

Every fill of one wallet — or of up to 1,000 wallets in one subscription — TWAP fills included: the same pairs the tradesByUser feed streams, filtered. Any address on Hyperliquid, not only wallets you control.
Create
Delivery

twapSliceFillsByUser

The fills a wallet’s TWAP orders executed — the same [wallet, fill] pairs, filtered to fills that carry a twapId. Group by twapId to follow one order.
Delivery

twapStatusesByUser

The node’s raw TWAP status records for one wallet, or for up to 1,000 wallets in one subscription — activated, finished, terminated, an error — as the twapStatusesByUser feed forwards them. These are the node’s records, not normalised lifecycle alerts. No snapshot is delivered: a webhook subscription gets status changes from the moment it is created. status in the source is a union: a string (activated, finished, …) or an object {"error": "reason"}. For filtering only, the object form matches "status": "error"; the delivered record keeps its original error object and reason. Other status strings pass through unchanged, so the filter is not restricted to today’s node vocabulary — the definitions describe this mapping.
Delivery

liquidations

Every liquidation on the exchange. data is an array of liquidation objects — not [wallet, fill] pairs — one per liquidated side of a trade, as the liquidations feed sends them. Use the filters to narrow it: a sz bound on a coin, for instance.
Create
Delivery

liquidationsByUser

Liquidations of one account, or of up to 1,000 accounts in one subscription. The subscription selects the liquidated account’s side, not the liquidator’s fills — a liquidator watching its own activity sees its side through tradesByUser.
Delivery

priceCross

A market’s price crossing a threshold. The condition lives in args; the type takes no filters.
Create
How a crossing is decided:
  • above fires when the previous price was at or below the threshold and the new price is above it; below is the inverse. Merely touching the threshold is not a crossing.
  • The first valid observation sets the baseline and does not notify.
  • Every observation within a source block is evaluated; several crossings inside one block are all kept in the delivery’s data array. Trade observations deduplicate counterparties by market and trade id.
  • mark observations use the same replica-action price extraction as mark candles (native universe name resolution and builder marks included); trade observations come from execution fills. Neither uses candle closes or infers unseen intrablock movement.
  • Observations are live-only: a crossing that happened entirely during an outage cannot be reconstructed, and no initial snapshot is delivered.
  • Deleting the subscription removes its baseline and pending deliveries; recreating it starts a fresh baseline.
The delivered frame is synthesised with channel: "priceCross"; each event in data is:
Delivery
Unlike the trade and TWAP types, liquidations and liquidationsByUser, priceCross deliveries are durable: baseline and pending delivery commit atomically to an outbox with stable delivery ids and retry schedules that survive a restart of the service. That is at-least-once delivery, not exactly-once processing — deduplicate on webhook-id. The outbox holds at most 32 pending deliveries per subscription, each at most 1 MiB; when a subscription’s share is full, its observation is rejected and logged without advancing the baseline, so a saturated subscription can miss its own crossings; total disk use scales with the number of subscriptions. See Plan limits.

Cohort bias types

Four types report how a trader cohort — apex, crowd, heavyweights, … (Trader cohorts) — is positioned on one coin: its netBias, from -1 (all short) to 1 (all long). They read a stored snapshot, normally taken every 15 minutes, so they tell you about a change at the next snapshot — not when a trade happens.
Create
The arguments and cohorts, how netBias is computed, the snapshot timing, the delivered row and a delivery example for each type are on Cohort bias types.

Liquidation risk types

Four types report potential liquidation exposure — positions that are still open, and how far the price is from their liquidation levels. Two watch one wallet’s positions; two watch a whole market. They are not executed liquidations: those are liquidations and liquidationsByUser. The service checks about once a minute, using positions and liquidation levels as last stored.
Create
The arguments, how the distance is computed, the timing, the delivered fields and an illustrative delivery for each type are on Liquidation risk types.