> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription types

> The Coinversa Pulse webhook subscription types — the six event types tradesByUser, twapSliceFillsByUser, twapStatusesByUser, liquidations, liquidationsByUser and priceCross, and the four cohort bias types cohortBias, cohortBiasFlip, cohortBiasOpposition and cohortBiasMove — with their args (one wallet or an array of up to 1,000 per subscription), filters, minimum plan, the delivered frame shape and a delivery example for each event type; the cohort bias delivery examples are on the Cohort bias types page. Four liquidation risk types, liquidationRiskCross, liquidationRisk, liquidationExposure and liquidationMap, are summarised here, with their own Liquidation risk types page.

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](#cohort-bias-types) report a trader cohort's positioning from stored snapshots and have a page of their own. The four [liquidation risk types](#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](https://docs.coinversa.ai/webhooks/api.md#definitions)).

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:

| Field | Type | Meaning |
| - | - | - |
| `channel` | string | The subscription type that produced the frame — `tradesByUser`, `liquidations`, `priceCross`, `cohortBiasFlip`, … |
| `seq` | number | The source position. Block height on the trade and TWAP types, on `liquidations` and `liquidationsByUser`, and on `priceCross` with `source: "trade"`; the replica block's Unix **nanoseconds** on `priceCross` with `source: "mark"`; the Unix **microseconds** at which the snapshot or observation was read on the four cohort bias types and the four liquidation risk types. Never compare one kind with another |
| `subscriptionId` | string | The subscription this delivery belongs to |
| `data` | array | The raw matching events — **only** those that passed your filters. An empty match produces no delivery |

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](https://docs.coinversa.ai/websocket/feeds.md#the-fill-object)), liquidation objects on `liquidations` and `liquidationsByUser` ([liquidations](https://docs.coinversa.ai/websocket/feeds.md#liquidations)), TWAP status records on `twapStatusesByUser` ([TWAP statuses](https://docs.coinversa.ai/websocket/feeds.md#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](https://docs.coinversa.ai/webhooks/cohort-bias.md#the-cohort-row) 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](https://docs.coinversa.ai/webhooks/liquidation-types.md#delivered-fields)).

## Filters

A filter is a field name with either an **exact** value or, for numeric fields, a **bounds object**:

```json theme={null}
{"coin": "BTC", "px": {"gte": "95000", "lt": "100000"}, "sz": "2.0"}
```

* 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](https://docs.coinversa.ai/webhooks/cohort-bias.md#filters)). Of the liquidation risk types only `liquidationRisk` takes a filter, `liquidationDistancePct` ([liquidation risk filters](https://docs.coinversa.ai/webhooks/liquidation-types.md#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}`.

```json Create theme={null}
{
  "type": "tradesByUser",
  "args": {
    "user": [
      "0x0123456789012345678901234567890123456789",
      "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]
  },
  "filters": {"coin": "BTC", "sz": {"gt": "1.5", "lte": "10"}},
  "url": "https://example.com/hook"
}
```

* 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](#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](https://docs.coinversa.ai/websocket/feeds) streams, filtered. Any address on Hyperliquid, not only wallets you control.

| | |
| - | - |
| `args` | `user` (required): one address, or an array of 1 to 1,000 addresses — lowercased, sorted and deduplicated ([one wallet or many](#one-wallet-or-many)) |
| Filters | `coin`, `side` (`A` sell / `B` buy), `px`, `sz`, `closedPnl` |
| Minimum plan | Free data — but Free has no subscription allowance, so Starter in practice |

```json Create theme={null}
{
  "type": "tradesByUser",
  "args": {"user": "0x0123456789012345678901234567890123456789"},
  "filters": {"coin": "BTC", "sz": {"gt": "1.5", "lte": "10"}},
  "url": "https://example.com/hook"
}
```

```json Delivery theme={null}
{
  "channel": "tradesByUser",
  "seq": 928110001,
  "subscriptionId": "…",
  "data": [
    [
      "0x0123456789012345678901234567890123456789",
      {
        "coin": "BTC",
        "px": "70000.5",
        "sz": "2.0",
        "side": "B",
        "time": 1788324615827,
        "startPosition": "0.0",
        "dir": "Open Long",
        "closedPnl": "0.0",
        "hash": "0xcdade62a4403e265cf2704437fc43c0201ec000fdf0701377176917d0307bc50",
        "oid": 533649007948,
        "crossed": true,
        "fee": "0.0245",
        "tid": 905724619509577,
        "feeToken": "USDC",
        "twapId": null
      }
    ]
  ]
}
```

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

| | |
| - | - |
| `args` | `user` (required): one address or an array of 1 to 1,000 ([one wallet or many](#one-wallet-or-many)) |
| Filters | `coin`, `side`, `px`, `sz`, `closedPnl` |
| Minimum plan | Free data — Starter in practice |

```json Delivery theme={null}
{
  "channel": "twapSliceFillsByUser",
  "seq": 928110001,
  "subscriptionId": "…",
  "data": [
    [
      "0x0123456789012345678901234567890123456789",
      {
        "coin": "BTC",
        "px": "70000.5",
        "sz": "0.01",
        "side": "B",
        "time": 1773878735890,
        "startPosition": "0.0",
        "dir": "Open Long",
        "closedPnl": "0.0",
        "hash": "0xabc1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
        "oid": 344895887371,
        "crossed": true,
        "fee": "0.0245",
        "tid": 111,
        "feeToken": "USDC",
        "twapId": 77738308
      }
    ]
  ]
}
```

## `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](https://docs.coinversa.ai/websocket/feeds#twap-statuses) 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.

| | |
| - | - |
| `args` | `user` (required): one address or an array of 1 to 1,000 ([one wallet or many](#one-wallet-or-many)) |
| Filters | `coin` (mapped from `state.coin`), `status`, `sz`, `executedSz`, `executedNtl`, `minutes` |
| Minimum plan | Pro |

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

```json Delivery theme={null}
{
  "channel": "twapStatusesByUser",
  "seq": 1156436426,
  "subscriptionId": "…",
  "data": [
    {
      "time": "2026-09-22T02:00:02.321152806",
      "twap_id": 2241180,
      "state": {
        "coin": "TAO",
        "user": "0x0123456789012345678901234567890123456789",
        "side": "B",
        "sz": "6.424",
        "executedSz": "0.0",
        "executedNtl": "0.0",
        "minutes": 58,
        "reduceOnly": true,
        "randomize": true,
        "timestamp": 1790042402321,
        "trigger": null,
        "stopPx": null
      },
      "status": "activated"
    }
  ]
}
```

## `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](https://docs.coinversa.ai/websocket/feeds#liquidations) sends them. Use the filters to narrow it: a `sz` bound on a `coin`, for instance.

| | |
| - | - |
| `args` | none |
| Filters | `coin`, `side`, `px`, `sz`, `closedPnl` |
| Minimum plan | Agent |

```json Create theme={null}
{
  "type": "liquidations",
  "filters": {"coin": "BTC", "sz": {"gte": "5"}},
  "url": "https://example.com/hook"
}
```

```json Delivery theme={null}
{
  "channel": "liquidations",
  "seq": 928109999,
  "subscriptionId": "…",
  "data": [
    {
      "time": 1773878735890,
      "liquidatedUser": "0x103c5e7a9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a",
      "liquidator": "0x7c66a1b2c3d4e5f60718293a4b5c6d7e8f901234",
      "coin": "BTC",
      "side": "A",
      "px": "68950.0",
      "sz": "6.2",
      "markPx": "68960.5",
      "method": "market",
      "hash": "0xabc1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
      "tid": 112,
      "penaltyFee": "1282.47",
      "closedPnl": "-41205.3"
    }
  ]
}
```

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

| | |
| - | - |
| `args` | `user` (required): the account — or an array of 1 to 1,000 accounts — whose liquidations you want ([one wallet or many](#one-wallet-or-many)) |
| Filters | `coin`, `side`, `px`, `sz`, `closedPnl` |
| Minimum plan | Agent |

```json Delivery theme={null}
{
  "channel": "liquidationsByUser",
  "seq": 928109999,
  "subscriptionId": "…",
  "data": [
    {
      "time": 1773878735890,
      "liquidatedUser": "0x0123456789012345678901234567890123456789",
      "liquidator": "0x7c66a1b2c3d4e5f60718293a4b5c6d7e8f901234",
      "coin": "ZRO",
      "side": "A",
      "px": "2.1027",
      "sz": "21.0",
      "markPx": "2.1023",
      "method": "market",
      "hash": "0xabc1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
      "tid": 111,
      "penaltyFee": "0.019075",
      "closedPnl": "-5.4747"
    }
  ]
}
```

## `priceCross`

A market's price crossing a threshold. The condition lives in `args`; the type takes **no filters**.

| | |
| - | - |
| `args` | `coin` (required); `threshold` (required, a positive decimal string); `source`: `mark` (default) or `trade`; `direction`: `above`, `below` or `both` (default) |
| Filters | none — extra predicates are refused |
| Minimum plan | Free data for both sources (the definitions export `sourceMinTiers` for `mark` and `trade`) — Starter in practice |

```json Create theme={null}
{
  "type": "priceCross",
  "args": {
    "coin": "BTC", "source": "mark",
    "threshold": "100000", "direction": "above"
  },
  "url": "https://example.com/hook"
}
```

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:

```json Delivery theme={null}
{
  "channel": "priceCross",
  "seq": 1773878735123456789,
  "subscriptionId": "…",
  "data": [
    {
      "coin": "BTC", "source": "mark", "threshold": "100000",
      "direction": "above", "previousPx": "99999", "px": "100001",
      "time": 1793923200000
    }
  ]
}
```

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](https://docs.coinversa.ai/webhooks/limits.md#queues-and-the-outbox).

## Cohort bias types

Four types report how a **trader cohort** — `apex`, `crowd`, `heavyweights`, … ([Trader cohorts](https://docs.coinversa.ai/concepts/cohorts.md)) — 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.

| Type | Fires | `args` | Filters | Minimum plan |
| - | - | - | - | - |
| `cohortBias` | Once with the current state when the subscription is created, then on each new snapshot, even if nothing changed | `coin` (required); `cohort`, `tierType` | `netBias`, `longNotional`, `shortNotional`, `accountCount` | Starter |
| `cohortBiasFlip` | A cohort's net bias goes from long to short or from short to long | `coin`, `cohort` (required); `direction`, `tierType` | `netBias`, `longNotional`, `shortNotional`, `accountCount` | Starter |
| `cohortBiasOpposition` | Two cohorts enter opposite positioning — on entry only, not while it persists | `coin`, `cohort`, `otherCohort` (required); `tierType` | none — the condition is in `args` | Starter |
| `cohortBiasMove` | Net bias has moved at least `points` percentage points from the last notified baseline | `coin`, `cohort`, `points` (required); `tierType` | `netBias`, `longNotional`, `shortNotional`, `accountCount` | Starter |

```json Create theme={null}
{
  "type": "cohortBiasFlip",
  "args": {"coin": "BTC", "cohort": "apex", "direction": "short"},
  "url": "https://example.com/hook"
}
```

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](https://docs.coinversa.ai/webhooks/cohort-bias.md).

## 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`](#liquidations) and [`liquidationsByUser`](#liquidationsbyuser). The service checks about once a minute, using positions and liquidation levels as last stored.

| Type | Fires | `args` | Filters | Minimum plan |
| - | - | - | - | - |
| `liquidationRiskCross` | A position's distance to its liquidation price crosses the threshold, for one wallet | `user` (exactly one wallet), `liquidationDistancePct` (required); `direction` | none — the condition is in `args` | Starter |
| `liquidationRisk` | That distance has moved at least `points` percentage points from the last notified baseline, for one wallet | `user` (exactly one wallet), `points` (required) | `liquidationDistancePct` | Starter |
| `liquidationExposure` | At least `minNotional` of a market's positions have liquidation levels within a `priceMovePct` move from the mark | `coin`, `priceMovePct`, `minNotional` (required); `direction`, `resetNotional` | none — the condition is in `args` | Starter |
| `liquidationMap` | A market's mark has moved at least `priceChangePct` from the reference price; delivers the full liquidation map | `coin`, `priceChangePct` (required); `buckets`, `range` | none — the condition is in `args` | Starter |

```json Create theme={null}
{
  "type": "liquidationRiskCross",
  "args": {
    "user": "0x0123456789012345678901234567890123456789",
    "liquidationDistancePct": "5",
    "direction": "below"
  },
  "url": "https://example.com/hook"
}
```

The arguments, how the distance is computed, the timing, the delivered fields and an illustrative delivery for each type are on [Liquidation risk types](https://docs.coinversa.ai/webhooks/liquidation-types.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.