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

# Webhooks for agents

> Use the Coinversa Pulse event inbox from an AI agent — inbox_subscribe creates an inbox subscription from a type, args and filters, inbox_subscriptions lists them, inbox_unsubscribe deletes one, inbox_state reports what is pending and inbox_drain reads and acknowledges messages — through the MCP server, with the same plan allowances as REST.

An agent connected to the [MCP server](https://docs.coinversa.ai/mcp/setup.md) can subscribe to events, read what they matched and unsubscribe from chat, with no server and no curl. The five tools below work on your account's [inbox](https://docs.coinversa.ai/webhooks/inbox.md): they create and manage **inbox subscriptions** only, act on the same account the portal and REST show, and are bound by the same plan allowance.

> [!NOTE]
>
> The MCP tools never take a URL. A subscription created from chat always delivers to the inbox, and the tools neither list nor delete HTTP subscriptions. To have frames POSTed to a URL you own, create the subscription in the [developer portal](https://developers.coinversa.ai) or over [REST](https://docs.coinversa.ai/webhooks/api.md#create-a-subscription).

## Subscribe

`inbox_subscribe` takes the same three things a REST create does — a `type`, its `args` and optional `filters` — and always sends `"deliveryMode": "inbox"`. Ask Claude to "watch 0x28f0…9bad's BTC fills of 1.5 or more" and it calls:

```json theme={null}
{
  "type": "tradesByUser",
  "args": {"user": "0x28f0d2a7c6b3e14f9a8b7c6d5e4f3a2b1c0d9bad"},
  "filters": {"coin": "BTC", "sz": {"gte": "1.5"}}
}
```

* **Types** are the ones on [Subscription types](https://docs.coinversa.ai/webhooks/events.md): the six event types `tradesByUser`, `twapSliceFillsByUser`, `twapStatusesByUser`, `liquidations`, `liquidationsByUser` and `priceCross`, and the four [cohort bias types](https://docs.coinversa.ai/webhooks/cohort-bias.md) `cohortBias`, `cohortBiasFlip`, `cohortBiasOpposition` and `cohortBiasMove`. The four [liquidation risk types](https://docs.coinversa.ai/webhooks/liquidation-types.md) `liquidationRiskCross`, `liquidationRisk`, `liquidationExposure` and `liquidationMap` are created the same way.
* **`args.user`** on the four by-user types is one address or an array of 1 to 1,000 — one subscription for all of them. `liquidations` takes no args. `priceCross` takes `coin` and a positive decimal-string `threshold`, with optional `source` (`mark` or `trade`) and `direction` (`above`, `below` or `both`). The cohort bias types take `coin` and, per type, `cohort`, `otherCohort`, `direction`, a decimal-string `points` and optional `tierType`. The two wallet liquidation risk types take **exactly one** `user` with `liquidationDistancePct` or `points`; the two market ones take `coin` with `priceMovePct` and `minNotional`, or `priceChangePct` — every number a string, `buckets` and `range` included ([arguments](https://docs.coinversa.ai/webhooks/liquidation-types.md#arguments)).
* **`filters`** are AND-combined: exact strings (`coin`, `side`) or `gt` / `gte` / `lt` / `lte` bounds on decimal strings. Numbers are always strings, never JSON numbers. `priceCross`, `cohortBiasOpposition`, `liquidationRiskCross`, `liquidationExposure` and `liquidationMap` accept no extra filters.

A cohort bias subscription is created the same way. Ask Claude to "tell me when Apex turns net short on BTC" and it calls:

```json theme={null}
{
  "type": "cohortBiasFlip",
  "args": {"coin": "BTC", "cohort": "apex", "direction": "short"}
}
```

Cohort positioning is a stored snapshot, normally taken every 15 minutes, so the flip reaches the inbox at the next snapshot — not when a trade happens — and the agent sees it the next time it drains. The message's `data` holds the cohort's row after the flip, with the row before it under `previous` ([`cohortBiasFlip`](https://docs.coinversa.ai/webhooks/cohort-bias#cohortbiasflip)).

The service validates the type, the field names and your plan, exactly as it does for REST: a type above your plan is refused with `403`, as is any subscription on **Free**, and a full allowance with `429` ([Plan limits](https://docs.coinversa.ai/webhooks/limits.md)). Inbox and HTTP subscriptions share the same slots. The tool returns a compact receipt — `subscribed`, `subscriptionId`, `deliveryMode`, `disabled` — and has no signing secret to show, because an inbox subscription has none.

A subscription is immutable: to change it, unsubscribe and subscribe again, which resets a price crossing's baseline and a cohort bias or liquidation risk subscription's state. Creation is never retried automatically, so after an ambiguous failure the agent should call `inbox_subscriptions` before trying again rather than risk a duplicate. There is no snapshot and no replay: a subscription collects from the moment it exists. `cohortBias` is the exception — it delivers the current state once when it is created — and `liquidationRiskCross`, `liquidationRisk` and `liquidationExposure` can deliver on their first check if the condition is already met.

## List and unsubscribe

`inbox_subscriptions` lists your inbox subscriptions — id, type, normalized `args`, `filters` and whether each is disabled — sorted by id, `limit` at a time (default 20, at most 100) with `offset`, `hasMore` and `nextOffset` to continue. HTTP subscriptions are left out, so their URLs never reach a chat transcript.

`inbox_unsubscribe` deletes one inbox subscription by its `subscriptionId`. It checks the id is an inbox subscription of yours first and refuses anything else; there is no bulk delete. Unsubscribing stops collection but keeps the messages already stored — they stay pending until drained or expired.

## Read the inbox

`inbox_state` reports the inbox without touching it: `pendingMessages`, `pendingBytes`, your plan's `maxMessages` and `maxStoredBytes`, and the two cumulative loss counters, `overflowDroppedTotal` and `expiredTotal`.

`inbox_drain` reads and **consumes**. It fetches the oldest pending messages (`count`, default 10, up to 1,000), keeps as many complete messages as fit the response budget, and acknowledges exactly those — a message it had to leave out stays pending for the next call, and a message's `data` is never split. Each message is the delivery envelope — `channel`, `seq`, `subscriptionId`, `data` — plus its `inboxId` and `receivedAt` ([the message](https://docs.coinversa.ai/webhooks/inbox.md#the-message)).

The result carries `messages`, `count`, `hasMore`, `acknowledged`, `ackStatus` and the inbox `state` as it was **before** the acknowledgement (`stateAt: "drain"`); call `inbox_state` for the current counts. Three things follow from the tool acknowledging for you:

* **A drain from chat deletes.** Unlike the REST [drain](https://docs.coinversa.ai/webhooks/inbox.md#drain-read-without-deleting), which is safe to repeat until you ack, the tool acks as part of the same call. There is no peek: use `inbox_state` to look without consuming.
* **`ackStatus: "unconfirmed"`** means the acknowledgement did not come back. The messages are still returned, but they may reappear on the next drain — deduplicate by `inboxId`.
* **Two drains at once** can return the same message. If several agents share an account, give one of them the job.

The inbox is per **account**: a drain returns what every inbox subscription matched, whichever key or surface created it, and what it acknowledges is gone for the portal and REST too. Messages nobody acknowledges expire after 14 days or are evicted on overflow — see [Limits](https://docs.coinversa.ai/webhooks/inbox.md#limits).

## The tools

| Tool | Kind | Backing route | What it does |
| - | - | - | - |
| `inbox_subscribe` | Creates a subscription | `POST /v1/subscriptions` | One inbox subscription from `type`, `args` and optional `filters`; never a URL |
| `inbox_subscriptions` | Read-only | `GET /v1/subscriptions` | Lists your inbox subscriptions, paged; HTTP subscriptions are excluded |
| `inbox_unsubscribe` | Destructive | `DELETE /v1/subscriptions/{id}` | Deletes one inbox subscription; stored messages are kept |
| `inbox_state` | Read-only | `GET /v1/inbox` | Pending counts, plan capacity and loss counters |
| `inbox_drain` | Destructive | `POST /v1/inbox/drain`, `POST /v1/inbox/ack` | Reads the oldest pending messages and acknowledges the ones it returns |

`inbox_subscribe`, `inbox_unsubscribe` and `inbox_drain` are the tools that change anything, and what they change is your Coinversa inbox subscriptions and inbox. The connector still never touches an exchange account, never signs and never trades.

## Hosted connections

The tools work the same however you connected. A connection made with **"Continue with Coinversa"** in Claude, ChatGPT or another client is authenticated for you and resolves the same account, plan and allowance as your API key; a connection made by pasting a key, and the npx package, use that key directly.

## What arrives

Whatever created the subscription and wherever it delivers, the frame is the same: the raw source frame plus `subscriptionId` — stored with an `inboxId` and `receivedAt` in the inbox, signed with [Standard Webhooks](https://docs.coinversa.ai/webhooks/signatures.md) headers when POSTed to a URL. An agent reading it should treat `data` as the WebSocket [fill objects](https://docs.coinversa.ai/websocket/feeds.md#the-fill-object) they are — sizes and prices as decimal strings, `side` as `A` (sell) or `B` (buy), `closedPnl` from the node — and say what happened, not what to do about it. On a cohort bias type `data` holds [cohort rows](https://docs.coinversa.ai/webhooks/cohort-bias.md#the-cohort-row) instead: report the cohort's net bias and the snapshot's time, which is when the snapshot was stored, not when the positioning changed. On a liquidation risk type `data` holds a wallet's positions or a market's exposure ([delivered fields](https://docs.coinversa.ai/webhooks/liquidation-types.md#delivered-fields)): report it as **potential** exposure from positions as last stored, checked about once a minute — not as a liquidation that happened, and not as a forecast of one. Market data is not advice.

## Roadmap

Today an agent **subscribes** and **pulls** what the subscriptions matched. Having the MCP server push an event into a running session is not something the protocol allows: the version the server speaks has no events capability. The inbox is the pull side of that: a session reads it when it is asked to, not when a fill lands.


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