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 onePOST whose body is the raw source frame plus the subscription it matched:
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 like1/2are rejected. Maximum length 128 characters. - The numeric operators are
gt,gte,ltandlte. There is noeq(use an exact value), no dollar sign, no expression tree and no arbitrary document path. - Exact text matching is case-sensitive:
BTCdiffers frombtc. - 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
400before 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.
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}.
- 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
userfield 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’schanneldo 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,
liquidationRiskCrossandliquidationRisk, are not among the four: theiruseris exactly one wallet, and the definitions advertisemaxItems: 1on 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.
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.
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.
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.
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.
priceCross
A market’s price crossing a threshold. The condition lives in args; the type takes no filters.
abovefires when the previous price was at or below the threshold and the new price is above it;belowis 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
dataarray. Trade observations deduplicate counterparties by market and trade id. markobservations use the same replica-action price extraction as mark candles (native universe name resolution and builder marks included);tradeobservations 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.
channel: "priceCross"; each event in data is:
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.
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 areliquidations and liquidationsByUser. The service checks about once a minute, using positions and liquidation levels as last stored.

