Notifications

The SDK consumes a realtime notification service where the solver publishes quote and position state transitions (instant open accepted, price filled, close requested, failures, and so on). It exposes that service two ways: a WebSocket live stream for real-time updates, and a REST search over stored history for backfill, replay, or audit.

The live stream delivers the normalized Notification shape on both protocols, so a UI consumes live frames through one code path. The stream reuses the SDK’s shared, reconnecting socket pool; the search dispatches on the resolved solver — the enigma notification service (POST /api/v1/search) or the rasa solver’s own position-state endpoint.

Each method and type has its own page with the full signature, parameters, return shape, and examples.

Protocol axis: `enigma` vs `rasa`

Notifications are configured per solver, and each solver’s endpoint speaks one of two wire protocols. The protocol is set on the solver’s notifications config (SymmioNotificationsConfig, discriminated by protocol: "enigma" | "rasa") and drives how the SDK subscribes and parses. Resolve it with config.getSolver({ chainId, solverId }).notifications. The call site — watchNotifications — is identical either way; only the transport underneath differs.

The protocol is a property of the solver, not the chain. Today HyperEVM’s enigma solver speaks enigma and Base’s rasa solver speaks rasa; watchNotifications / searchNotifications take an optional solverId and dispatch on the resolved solver’s protocol. See Solvers & Chains for how the registry ties a solver to its notifications config.

	`enigma`	`rasa`
Subscribe frame	`channel_patterns` scoped to one account (per channel)	`{ "address": [...] }` — the watched SubAccount address list
Socket sharing	One pooled socket per endpoint and account	One multiplexed hub socket per endpoint; every account shares it
Frame shape	Envelope-wrapped (`EnigmaNotificationEnvelope`)	Bare frame, no envelope
`account` on the wire	Hoisted from the envelope’s top-level `address`	Absent — stamped from the subscription (wire carries `counterparty_address` only)
History search	Notification service — `searchUrl` + `POST /api/v1/search` (stored documents)	The solver’s own position-state endpoint — `POST /position-state/{start}/{size}` (no notification-service `searchUrl`)
Config type	`SymmioEnigmaNotificationsConfig` (adds `channel` + `searchUrl`)	`SymmioRasaNotificationsConfig`

One search interface, dispatched by solver. searchNotifications covers both kinds: an enigma solver hits the notification service, a rasa solver hits its own position-state endpoint. It returns a per-kind union — narrow on the result’s kind, or pass a literal solverId. The live stream also works identically on both protocols.

Live stream

watchNotifications

Subscribe to live position/quote state notifications for one account over the pooled WebSocket.

REST search

searchNotifications

Search a solver’s stored notification history — one interface over both kinds, dispatched by solverId (enigma notification service or the rasa position-state endpoint). Returns a per-kind union.

Helpers

normalizeNotification

Turn a raw wire frame into a normalized Notification.

classifyNotification

Classify a raw action_status into a NotificationType.

parseNotificationFrame

Parse an inbound socket frame into a raw notification for a given protocol, or null for control/malformed frames.

buildSubscribeMessage

Build the enigma channel_patterns subscribe frame sent on every (re)connect.

buildRasaSubscribeMessage

Build the rasa subscribe frame — the { "address": [...] } list of watched SubAccounts.

Types

Notification

The normalized, classified notification the SDK delivers to consumers.

RawPositionNotification

The snake_case wire frame as it arrives from the service — a base plus per-protocol variants union (RawEnigmaPositionNotification | RawRasaPositionNotification).

NotificationType

Broad classification derived from a frame’s action_status.

NotificationSearchFilter

The enigma-only advanced equality filter accepted by searchNotifications.

NotificationSearchResult

The per-kind union result of searchNotifications — EnigmaNotificationSearchResult | RasaNotificationSearchResult; narrow on kind.

RawEnigmaPositionNotification

The enigma wire variant, after the envelope unwrap — adds va_address, failure_message, version.

RawRasaPositionNotification

The rasa wire variant, bare — adds order_type.

EnigmaNotificationEnvelope

The { data, address } envelope the enigma endpoint nests each frame in.

Solvers & Chains — the registry that sets each solver’s notifications config and protocol (enigma vs rasa).
WebSocket concept — the pooled, reconnecting socket primitive and the SocketStatus lifecycle behind watchNotifications.
Unified Quotes — classifyQuoteNotificationAction and applyNotificationToQuotes consume these frames, but live in the quotes domain, not here.
TP/SL — conditional-order state transitions arrive on a separate channel with their own frame shape.
React useNotifications — the hook wrapper over this stream and search for React apps.