Event catalog

Every realtime event delivered after scope.confirmed shares the same envelope. The type strings are the canonical FirmEventType enum from tradara-core/services/firm-ws/api/asyncapi.yaml — the same strings accepted by POST /v1/firm-control/webhooks as event_types.

Envelope

{
  "schema": "ws.firm.v1",
  "type": "trades.closed",
  "firm_id": "660e8400-e29b-41d4-a716-446655440001",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "seq": 1048393,
  "ts": "2026-04-09T14:00:00.000Z",
  "source_service": "trades",
  "source_subject": "ws.firm.v1.660e8400-….550e8400-….6ba7b810-….trades.closed",
  "data": { }
}

Field	Description
`schema`	Always `ws.firm.v1`. Use this to discriminate envelopes from control frames.
`type`	Canonical `{entity}.{event}` — same value used as a webhook `event_types` entry.
`firm_id`	Firm this event belongs to (echoes your `connected` frame).
`user_id`	Trader UUID. Absent or empty string for firm-tier-only events.
`account_id`	Account UUID. Absent or empty for firm/user-meta events.
`seq`	JetStream sequence. Persist the highest you’ve processed for reconnect via `?last_seq=`.
`ts`	Publisher timestamp, RFC3339 with nanoseconds.
`source_service`	Originating Tradara service (`orders`, `fills`, `trades`, `identity`, `footprint`, …).
`source_subject`	Full NATS subject the event was published to.
`data`	Service-defined payload. When undefined in AsyncAPI, the shape matches the corresponding REST resource on this site.

Tiers

Each event type is published at one of three tiers, matching the scope you must subscribe with to receive it. account-tier events are also visible to broader user and firm scopes.

Users & relationships

`type`	Tier	Typical use
`users.created`	user	New trader profile visible to firm
`users.updated`	user	Profile or relationship-driven user update
`relationships.created`	firm	Trader onboarded / relationship created
`relationships.updated`	firm	Relationship metadata changed
`relationships.revoked`	firm	Trader removed from firm
`relationships.status_changed`	firm	Active / suspended / etc.

Accounts

`type`	Tier	REST reference
`accounts.created`	account
`accounts.updated`	account
`accounts.closed`	account
`accounts.locked`	account	Lock and unlock
`accounts.unlocked`	account	Lock and unlock
`accounts.phase_advanced`	account
`accounts.passed`	account
`accounts.status_changed`	account
`accounts.config_updated`	account
`accounts.personal_risk_lock_armed`	account

Evaluation pass and lineage

Build against the dedicated pass events — do not treat a bare accounts.created with account_type: sim_funded as the pass signal alone (that create still fires for the new funded account).

Signal	What to use
Evaluation passed (terminal, no funded mint)	`accounts.passed`
Phase advanced / upgraded to funded	`accounts.phase_advanced` on the evaluation account
Funded account minted from a pass	`accounts.created` with `predecessor_account_id` set to the evaluation
Pass vs breach on status	`accounts.status_changed` with `status_change_reason` `evaluation_passed` / `evaluation_upgraded` (breach uses reasons like `daily_loss_limit` and `hard_breach: true`)

Lineage fields on account payloads:

Field	Meaning
`successor_account_id`	On an upgraded evaluation: the funded account minted from it
`predecessor_account_id`	On a funded account: the evaluation it came from
`account_name`	Generated display name (prefixes like `ONYXEV` / `ONYXSF`)

Trading

`type`	Tier	REST reference
`orders.state`	account	Order lifecycle
`orders.ack`	account	Place an order
`orders.cancelled`	account	Flatten and cancel
`fills.persisted`	account	List fills
`fills.fee_computed`	account	List fills
`fills.voided`	account	List fills
`positions.created`	account	Read orders and positions
`positions.updated`	account	Read orders and positions
`positions.closed`	account	Read orders and positions
`trades.opened`	account	List trades
`trades.closed`	account	List trades
`trades.rebuilt`	account	List trades
`balances.updated`	account	Get balance
`stats.updated`	account	Trading stats

Risk

`type`	Tier
`risk.breach`	account
`risk.account_locked`	account

Footprint / fraud signals

These are user-tier. Subscribe with scope: firm or scope: user — scope: account does not include …meta.ip_logs.* / …meta.fingerprints.*.

`type`	Tier	Emitted
`ip_logs.created`	user	When footprint ingest has `firm_id` and `user_id`
`ip_logs.flagged`	user	IP newly shared by ≥2 users
`devices.flagged`	user	Device newly shared by ≥2 users
`fingerprints.flagged`	user	Same trigger as `devices.flagged` (Fingerprint `visitor_id`)
`devices.seen`	user	Reserved — not emitted yet
`fingerprints.seen`	user	Reserved — not emitted yet

Hedge monitoring

`type`	Tier
`hedge.incidents.flagged`	firm
`hedge.incidents.resolved`	firm
`hedge.cluster.updated`	user

Webhook parity: any emitted type on this page is a valid entry in the event_types array on POST /v1/firm-control/webhooks. Reserved types are in the enum so clients can ignore unknown values without a breaking change. Pick the delivery channel based on durability and latency — the catalog is the same.

Catalog changelog

Additive enum values ship without a deprecation window. This list is the versioned record of FirmEventType changes. The spec in tradara-core/services/firm-ws/api/asyncapi.yaml is canonical.

Date	Change
2026-08-30	Added `positions.created` (already on the wire). Documented `fingerprints.flagged` as emitted on shared-device detection. Marked `devices.seen` / `fingerprints.seen` as reserved.

Overview

Account Provisioning

Terminal Embed

Firm & Users

Staff & RBAC

Offerings & Acceptance

API Keys

Webhooks

Realtime WebSocket

Operations

Firm Backoffice Reads

Terminal Onboarding (JWT)

Envelope

Tiers

Users & relationships

Accounts

Evaluation pass and lineage

Trading

Risk

Footprint / fraud signals

Hedge monitoring

Catalog changelog

​Envelope

​Tiers

​Users & relationships

​Accounts

​Evaluation pass and lineage

​Trading

​Risk

​Footprint / fraud signals

​Hedge monitoring

​Catalog changelog

Envelope

Tiers

Users & relationships

Accounts

Evaluation pass and lineage

Trading

Risk

Footprint / fraud signals

Hedge monitoring

Catalog changelog