---
title: "User events"
description: "User-specific events (requires user-level auth via authenticate action or token query param). Streams order confirmations, balance updates, and a venue-agnostic order lifecycle event (order_event) covering DAG steps and terminal fill / failure status across all venues."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## Connection

```
wss://ws.agg.market/ws
```

Production WebSocket server.

**Connection:** `wss://ws.agg.market/ws?appId=xxx` (required). Optionally pass `&token=eyJ...` for user-level auth on connect.

**Reconnection:** Reconnect with exponential backoff + jitter: `delay = min(1s × 2^attempt + random(0–1s), 30s)`. On reconnect, re-subscribe to all channels.

**Heartbeat:** The service emits a JSON `heartbeat` message clients can observe directly.

### Security schemes

<ParamField body="appId" type="userPassword">
  App-level auth: pass appId as a query parameter on connect. Required for all connections. The appId must belong to an active app with matching allowed origins.
</ParamField>
<ParamField body="jwt" type="JWT">
  User-level auth: pass JWT as token query param on connect, or send &#123; action: 'authenticate', token &#125; mid-session. Required for user-specific events (orders, balances). Same JWT as the REST API.
</ParamField>

## Receive

### Order submitted

Order confirmation after trade execution (user-level auth required)

<ParamField body="type" type={"\"order_submitted\""} required />
<ParamField body="venue" type="string" required />
<ParamField body="orderId" type="string" required />
<ParamField body="side" type="string" required />
<ParamField body="price" type="number" required />
<ParamField body="size" type="number" required />
<ParamField body="outcomeId" type="string" />
<ParamField body="timestamp" type="number" required />

```json
{
  "type": "order_submitted",
  "venue": "polymarket",
  "orderId": "ord_abc123",
  "side": "buy",
  "price": 0.55,
  "size": 100,
  "outcomeId": "clv2abc123def456",
  "timestamp": 1710000000000
}
```

### Balance update

Balance update after execution (user-level auth required)

<ParamField body="type" type={"\"balance_update\""} required />
<ParamField body="venue" type="string" required />
<ParamField body="tradingBalanceCents" type="number" required />
<ParamField body="walletBalanceCents" type="number" />
<ParamField body="timestamp" type="number" required />

```json
{
  "type": "balance_update",
  "venue": "polymarket",
  "tradingBalanceCents": 94500,
  "walletBalanceCents": 100000,
  "timestamp": 1710000000000
}
```

### Order lifecycle event

Venue-agnostic DAG and order lifecycle stream. Discriminate on the `event` field. Emitted for every venue automatically.

<ParamField body="type" type={"\"order_event\""} required />
<ParamField body="event" type={"\"dag_started\" | \"dag_completed\" | \"dag_failed\" | \"dag_cancelled\" | \"step_started\" | \"step_completed\" | \"step_waiting\" | \"step_failed\" | \"step_retrying\" | \"filled\" | \"partial_fill\" | \"failed\""} required />
<ParamField body="userId" type="string" required />
<ParamField body="orderId" type="string" required />
<ParamField body="venue" type="string" />
<ParamField body="filledAmountRaw" type="string" />
<ParamField body="remainingAmountRaw" type="string" />
<ParamField body="errorReason" type="string" />
<ParamField body="dagRunId" type="string" />
<ParamField body="stepId" type="string" />
<ParamField body="stepType" type="string" />
<ParamField body="templateName" type="string" />
<ParamField body="attempt" type="number" />
<ParamField body="timestamp" type="number" required />

```json
{
  "type": "order_event",
  "event": "dag_started",
  "userId": "usr_xyz789",
  "orderId": "ord_abc123",
  "venue": "polymarket",
  "filledAmountRaw": "string",
  "remainingAmountRaw": "string",
  "errorReason": "string",
  "dagRunId": "string",
  "stepId": "string",
  "stepType": "string",
  "templateName": "string",
  "attempt": 0,
  "timestamp": 1710000000000
}
```