Skip to main content
Every route on this page is relative to one base URL and, except /health, authenticated:
Subscriptions belong to the account, not to a particular key: any of your keys sees and manages all of them, and they share one allowance and one inbox. The same operations are in the developer portal’s Webhooks page and, for inbox subscriptions and reading the inbox, in the MCP tools.
This API is served by webhook.coinversa.ai, not the data API at api.coinversa.ai. It takes Authorization: Bearer, not X-API-Key, and it is not in the data API’s OpenAPI spec. REST auth failures are 403 on the data API; here a missing or invalid key is 401.

Authentication

One header, the same key as REST and the WebSocket:
Subscriptions and the inbox belong to the account, not to one key: sibling keys on the same account see and manage the same subscriptions and share the allowance. Connections made through the hosted MCP connector are authenticated for you; nothing to configure. Missing or invalid credentials, and unknown, revoked or suspended keys, are 401. An auth-backend outage is 503, never anonymous access — treat a 503 as temporarily unavailable and retry, not as a bad key.

Summary

Every authenticated row takes the Bearer header above.

Definitions

GET /v1/subscriptions/definitions → { "types": [...], "filterLogic": "and" }. Only the types permitted by your tier are listed, so Free sees the Free-tier types even though its subscription allowance is zero: feed access and subscription allowance are separate checks. The same declarations drive validation and event field extraction — this is not an arbitrary query interface. Each type carries:
The example omits the other trade fields for brevity. minItems and maxItems on user mean it accepts one address or an array of 1 to 1,000 (one wallet or many). Read the endpoint rather than maintaining a client-side list.

Create a subscription

POST /v1/subscriptions
args selects and configures the source independently of the optional filters. The original top-level user spelling is still accepted, but do not send user both at the top level and inside args.

One wallet or many

On the four by-user types args.user is one address string or an array of 1 to 1,000 addresses; the definitions advertise minItems: 1 and maxItems: 1000 on the argument. The top-level user spelling accepts either form too.
  • One array is one subscription against your allowance and one underlying processor feed; it does not change the type’s minimum plan.
  • Addresses are lowercased; arrays are 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. Creation bodies are limited to 64 KiB.
  • In create and list responses a one-element array — including one left after deduplication — is returned as a string; the legacy top-level user 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, with the same filters applied to each. Non-wallet arguments stay single-valued.

Cohort bias types

The four cohort bias types take coin and, depending on the type, a cohort, a second cohort, a direction or a number of points. One body per type, with every required argument:
  • coin is required on all four, matched case-insensitively, and can be a qualified symbol such as xyz:GOLD.
  • tierType is optional on all four: pnl (default), size, pnl_recent or size_recent. A cohort or otherCohort must belong to that classification — a cohort from the other one is a 400 — and cohortBiasOpposition needs two different cohorts.
  • direction on cohortBiasFlip is long, short or both (default): the side the cohort flips to.
  • points on cohortBiasMove is a positive decimal string, at most 200: percentage points of net bias.
  • cohortBias, cohortBiasFlip and cohortBiasMove accept the netBias, longNotional, shortNotional and accountCount filters; cohortBiasOpposition accepts none.
They are evaluated on stored snapshots, normally taken every 15 minutes, not on each trade. What each one fires on, the cohorts and the delivered rows are on Cohort bias types.

Liquidation risk types

The four liquidation risk types take either one wallet or one market, and a threshold. One body per type, with every required argument:
  • user on liquidationRiskCross and liquidationRisk is exactly one wallet — a string or a one-element array. A second address is a 400. There is no coin argument: every open position on record for the wallet is checked.
  • liquidationDistancePct on liquidationRiskCross is a positive decimal string in percent ("5" is 5%); direction is above, below or both (default), and below is closer to liquidation.
  • points on liquidationRisk is a positive decimal string — percentage points of distance, with no upper limit. It is the one type of the four that takes a filter: liquidationDistancePct.
  • coin on liquidationExposure and liquidationMap is matched case-insensitively and can be a qualified symbol such as xyz:GOLD.
  • priceMovePct on liquidationExposure is a decimal string above 0 and at most 100; minNotional is a positive decimal string in quote units. direction is down, up or both (default). resetNotional is optional, positive and at most minNotional, and defaults to it.
  • priceChangePct on liquidationMap is a positive decimal string. buckets and range are optional integer strings: "1" to "200" (default "50") and "1" to "100" (default "30").
They are evaluated about once a minute on stored positions and liquidation levels, not on each price tick. What each one fires on and the delivered fields are on Liquidation risk types. The response carries the subscription — type, the normalised args, the saved filters, its id, deliveryMode, url and disabled status — and, on creation of an http subscription only, the whsec_… signing secret. List responses never include it; read it later with GET /v1/subscriptions/{id}/secret.

Inbox delivery

Send "deliveryMode": "inbox" and no url, and matching frames are stored in your account’s one inbox instead of being POSTed — the same types, args and filters, one of the same subscription slots, no signing secret, and 403 on Free. Read them with the three inbox routes below. The full contract is on Inbox delivery.
A subscription’s configuration is immutable: delete and recreate to change it, which also resets priceCross crossing state and a cohort bias or liquidation risk subscription’s state. If activating the underlying feed fails, creation rolls back and answers 503 rather than leaving a saved subscription behind. Errors: 400 (invalid format, unknown type, argument, filter or operator, impossible range, an empty or over-1,000 user array or an invalid address in it, a cohort outside the chosen tierType, points outside its range, more than one wallet on a liquidation risk type, priceMovePct above 100, resetNotional above minNotional, buckets or range that is not an integer string in its range, a body over 64 KiB — checked before anything is saved), 403 (the type is not permitted by your tier, or an inbox subscription on Free), 429 (your account is at its subscription allowance), 503 (auth, storage or feed unavailable). Tier checks are creation-time checks, not continuous re-authorisation of saved subscriptions after an account change.

List subscriptions

GET /v1/subscriptions → this account’s subscriptions, each with its type, args, filters, id, deliveryMode ("http" or "inbox"), url (HTTP subscriptions) and disabled status. No secrets.

Delete a subscription

DELETE /v1/subscriptions/{id} deletes one subscription you own. For priceCross, the cohort bias types and the liquidation risk types it also removes the stored baseline or state and any pending deliveries in the outbox. Deleting an inbox subscription stops collection but does not delete the messages it already stored — acknowledge those on the inbox.

Delete all subscriptions

DELETE /v1/subscriptions deletes every subscription on the account.

Re-enable a subscription

POST /v1/subscriptions/{id}/enable re-enables a subscription that a 410 from your URL disabled. It is idempotent. It answers 429 if the account is already at its subscription allowance — a disabled subscription does not count toward it, so enabling one is a creation-time check again.

Read the signing secret

GET /v1/subscriptions/{id}/secret returns the subscription’s whsec_… signing secret — the one returned at creation. There is one secret per subscription and no rotation; see Signatures and delivery. An inbox subscription has no secret, and this route answers 400 for it.

Inbox

Three routes read the account’s one inbox; the semantics are on Inbox delivery. A message is the delivery envelope plus inboxId (msg_ + 32 hex) and receivedAt (the message).

Health

GET /health needs no key and answers 200 while the service is up. The body is a JSON object of counts — subscriptions (saved subscriptions), feeds (active feed subscriptions), queued (fresh deliveries waiting), retrying (retries waiting) and outbox (pending outbox rows). Treat the status code as the health signal and the body as informative: a build may answer 200 with an empty body, so accept both. It does not check auth or feed readiness.

Delivery semantics

What a delivery looks like is on Signatures and delivery. The status codes your URL returns mean:

Errors

Error bodies are plain text, not JSON — Unauthorized, unknown webhook type, endpoint must be a public HTTPS URL, invalid subscription JSON, filter "sz" has an impossible range — so match on the status code and show the text. The tentative subscription allowances per plan are on Plan limits.