# Event volume (events)


Source: https://docs.stxapp.io/websockets/channels/events/

Topic: `events`

Traded volume per event: one number covering every market on it, so a client showing
"$12,430 vol" on an event card need not fetch that event's markets and add them up.

One topic covers every event, narrowed by the join payload. Ten events is one join, not
ten.

## Joining

```
["1","1","events","phx_join",{"event_ids":["<uuid>","<uuid>"]}]
```

**At least one valid `event_id` is required.** As on `orderbook`, an absent or unusable
list is an error, not "no filter"; every event on the exchange is not served here.

```json
{"status":"error","response":{"reason":"event_ids_required"}}
```

The reply echoes the filter and carries each event's current value, so a client paints
before the next trade:

```json
{"status":"ok","response":{
  "selected_event_ids":["<uuid>"],
  "events":[{"event_id":"<uuid>","volume":"12430.0000"}]}}
```

An event with nothing recorded is **omitted from `events`**, not reported as zero, so
"not known yet" stays distinct from "nothing traded". Its id is still echoed in
`selected_event_ids`.

`orderbook` and `ticker` send no snapshot because their producers republish on a cadence.
Event volume moves only on a trade, so without this a client sits blank while the event
is quiet.

## Server pushes

`event`, one message per event whose value changed:

```json
{"event_id":"...","volume":"12455.0000"}
```

`volume` is the event's **lifetime traded volume in dollars** across every active market
on it, a dollar string; see [Wire format](/websockets/channels/wire-format/#the-format).

**Every push is the whole current value, not a delta.** Replace what you hold for that
`event_id`; never add to it.

Pushes are coalesced to at most one per event per second, and an unchanged figure pushes
nothing.

:::tip[Ignore keys you do not know]
Fields will be added: market counts, open interest, event status. Treat an unknown key
as ignorable rather than an error and a client written today keeps working.
:::

## Changing which events stream

```
["1","2","events","select_event_ids",{"event_ids":["<uuid>"]}]
```

Same non-empty rule; an unusable list keeps the current selection and replies with an
error. The reply has the join reply's shape, current values included.

## Use Cases

| Use case | Message to send |
| --- | --- |
| Join for two events | `["3","3","events","phx_join",{"event_ids":["<uuid>","<uuid>"]}]` |
| Change which events stream | `["3","4","events","select_event_ids",{"event_ids":["<uuid>"]}]` |
| Keep the channel alive | `["3","5","events","ping",{}]` |