Skip to main content
Four subscription types watch how a trader cohort is positioned on one coin — net long or net short, and by how much. cohortBias delivers the cohort rows of every new snapshot. cohortBiasFlip, cohortBiasOpposition and cohortBiasMove deliver only when something changed between two snapshots: a cohort changed side, two cohorts took opposite sides, or a cohort’s net bias moved by a number of points. All four need Starter or above, and deliver the way every other subscription type does: a signed POST to your URL, or the inbox. They describe positioning — they are not a recommendation to trade. Delivery examples are illustrative: the values are made up.

Snapshot timing

Cohort positioning is a stored snapshot, normally taken every 15 minutes. The service checks for a new snapshot about once a minute. So these types tell you about a change at the next snapshot — not when a trade happens.
  • A change that happens and reverses between two snapshots is not seen.
  • The times in a delivery — snapshotTime and recordedAt — are the snapshot’s own: when it was taken and when it was stored. They are not the time the positioning changed.
  • A transition is the difference between the newest snapshot and the last one your subscription saw. If the service misses snapshots during an outage, the ones in between are not replayed.
  • A snapshot that cannot be read, or that has no rows for your coin, changes nothing: no delivery, and no flip, opposition or move.
  • A new subscription starts from the snapshot already stored when you create it. The service hands it over at its next check, about once a minute: cohortBias delivers it, and for the other three it only sets the starting state. The next new snapshot is the first that can produce a flip, an opposition or a move.

The four types

Arguments

The cohorts are the tiers on Trader cohorts:
  • pnl_recent and size_recent are the same cohorts on the 30-day tiers.
  • A cohort from the other classification — heavyweights with tierType: "pnl" — is a 400. So is cohortBiasOpposition with the same cohort twice, and points that is not above 0 or is above 200.
  • The legacy slugs the REST API returns (money_printer, exit_liquidity, …) are accepted in cohort and otherCohort and normalised. Deliveries carry the names above.
  • coin is not checked against a list of markets when you create the subscription: a symbol with no snapshot rows is accepted and delivers nothing.

Net bias

netBias is the cohort’s signed long-short ratio on the coin, from -1 to 1:
Positive is net long, negative is net short, 0 is neutral. 1 means every position the cohort holds on the coin is long; -0.4 means shorts outweigh longs by 40% of the cohort’s total notional. It is delivered as a decimal string and compared with exact decimal arithmetic.

Filters

cohortBias, cohortBiasFlip and cohortBiasMove accept four numeric filters, applied to the cohort’s current row: Each takes an exact value or gt / gte / lt / lte bounds, as decimal strings, AND-combined — the rules on Filters. A count is a string here too: {"accountCount": {"gte": "100"}}.
  • On cohortBias, a row that does not pass is left out of data; if none passes, nothing is delivered for that snapshot.
  • On cohortBiasFlip, a flip is delivered only if the row after the flip passes.
  • On cohortBiasMove, a move whose row does not pass is not delivered and does not reset the baseline.
  • cohortBiasOpposition takes no filters — extra predicates are refused.

The cohort row

Every event in data is one cohort’s row from the snapshot: The three transition types add fields to the row:

cohortBias

A cohort’s positioning on one coin, snapshot by snapshot. It delivers once with the current state when you create the subscription, then again on each new snapshot — normally every 15 minutes — even if no value changed. That first delivery is not part of the create response: it follows at the service’s next check, about once a minute. Without cohort, data holds a row for every cohort of the classification that the snapshot has; with it, that cohort’s row only.
Create
The sample is cut to two of the eight rows:
Delivery

cohortBiasFlip

A cohort changing side: its net bias was long in one snapshot and is short in the next, or the reverse. direction is the side it flips to — "short" delivers long-to-short flips only.
  • A reading of exactly 0 is neutral, not a side: moving to it or from it is not a flip.
  • The comparison is between two consecutive snapshots your subscription saw. The one already stored when you subscribe only sets the starting state; the next new snapshot is the first that can be a flip.
Create
Delivery

cohortBiasOpposition

Two cohorts taking opposite sides of one coin: one is net long and the other net short. It fires on entry only — when the snapshot before did not have them opposed — and not again while the opposition persists. The two swapping sides while still opposed is not a new entry. Both cohorts must be in the snapshot and in the one before it. The delivered event is the cohort row, with the second cohort under other:
Create
Delivery

cohortBiasMove

A cohort’s net bias moving by at least points percentage points from a baseline. The baseline is the reading you were last notified about — or, before the first notification, the first reading the subscription saw. After it fires, the new value is the baseline. The rule is abs(netBias - baseline netBias) * 100 >= points. These are points of net bias, not a relative percent: with points: "10" and a baseline of 0.20, readings of 0.24 and 0.28 do not fire — small moves accumulate against the same baseline — and 0.32 does, with changePoints: "12". 0.32 is then the baseline. changePoints is signed: negative when the bias moved toward short.
Create
previous is the baseline row, which can be several snapshots old:
Delivery

State and delivery

  • The first observation seeds state. The first snapshot a subscription sees — the one already stored when you create it, read at the service’s next check — never produces a flip, an opposition or a move by itself: it is what the next one is compared with. cohortBias is the type that delivers on it.
  • A missing cohort is unavailable, not zero. When a cohort is absent from a snapshot and later returns, that reading starts a fresh baseline: nothing is reported against the reading before the gap.
  • A snapshot is evaluated once per subscription. One the subscription has already seen is not delivered again.
  • seq on these four types is the Unix time, in microseconds, at which the service first read that snapshot. It is not a block height and not the snapshot’s own time — that is snapshotTime — and it is not comparable with the seq of any other type (the delivered frame).
  • Deliveries are durable, as on priceCross: the subscription’s state and the pending delivery — or the inbox message — commit together, and HTTP deliveries wait in the same outbox, at most 32 pending per subscription (Plan limits). If a subscription’s share is full, a new notification is rejected and logged, and its state does not advance. Delivery is at least once: deduplicate on webhook-id.
  • Subscriptions are immutable. Delete and recreate one to change it; that also clears its state, so the snapshot that is current when you recreate it seeds it again.