watchNotifications

Subscribe to live position/quote state notifications for one account.

Opens (or reuses) one reconnecting socket to the resolved solver’s notifications endpoint, sends the subscribe frame on every (re)connect, normalizes inbound frames into Notifications, and invokes your handlers.

It is a thin per-protocol dispatch: it resolves the target solver (config.getSolver({ chainId, solverId })), reads its notifications.protocol, and hands off to that protocol’s adapter, which owns the subscribe frame, parse, and socket-sharing story. The call site is identical either way:

enigma (HyperEVM lowcap): watchers sharing the same endpoint and account share one pooled socket. The subscribe frame is a channel_patterns frame (buildSubscribeMessage), and each inbound push is unwrapped from its EnigmaNotificationEnvelope.
rasa (Base position-state): every account multiplexes onto one hub socket per endpoint — the subscribe frame carries the full watched-address list (buildRasaSubscribeMessage), and each watcher receives only its own account’s frames, with notification.account stamped from the subscription (the rasa wire only carries counterparty_address, no address).

Either way, the socket closes when the last watcher unwatches.

The protocol is fixed by the resolved solver’s registry entry — see Solvers & Chains. Pass solverId to pick a non-default solver; you never pass or branch on the protocol here.

This is a subscribe function, not a query — there are no query options. For a React binding, use the useNotifications hook.


import { watchNotifications } from "@symmio/trading-core";
 
const unwatch = watchNotifications(config, {
  account: "0xaccount...",
  onNotification: (n) => console.log(n.type, n.quoteId),
  onStatusChange: (status) => console.log(status),
  onError: (err) => console.error(err),
});
 
// later, dispose (idempotent):
unwatch();

Parameters

accountAddressrequired

SubAccount address to subscribe for.

chainIdnumberoptional

Target chain id. Defaults to the config’s defaultChainId.

solverIdSolverIdoptional

Target solver — selects the notifications endpoint and protocol. Defaults to the chain’s default solver.

onNotification(n: Notification) => voidrequired

Called for every normalized notification frame.

onStatusChange(s: SocketStatus) => voidoptional

Called whenever the underlying connection status changes. SocketStatus is "connecting" | "open" | "reconnecting" | "closing" | "closed".

onError(e: SymmError) => voidoptional

Called on a transport or parse error; does not stop the subscription.

Returns

Unwatch

Call to stop the subscription; idempotent. The pooled socket closes when the last watcher releases.

Throws

Throws a SymmError synchronously when the chain is unsupported or no WebSocket implementation is available.

`buildRasaSubscribeMessage`

The subscribe frame builder for the rasa protocol. watchNotifications calls it internally on the shared hub socket; it is exported for tooling and tests that assert the exact wire frame. The enigma protocol uses buildSubscribeMessage instead.


import { buildRasaSubscribeMessage } from "@symmio/trading-core";
 
buildRasaSubscribeMessage(["0xabc…", "0xdef…"]);
// '{"address":["0xabc…","0xdef…"]}'

A rasa endpoint carries many SubAccounts on one connection, so the hub always (re)sends the complete current address list — correct whether the server treats the frame as a replacement or as cumulative.

addressesreadonly Address[]required

The full list of SubAccount addresses this socket currently watches.

string

The { "address": [...] } frame serialized as a JSON string, ready to send.

Notifications overview — the enigma vs rasa protocol axis.
Solvers & Chains — which chain speaks which notifications protocol.
WebSocket concept — pool, reconnect, and the SocketStatus lifecycle.
buildSubscribeMessage — the enigma subscribe-frame builder.
searchNotifications — the REST history counterpart, one interface over both solver kinds.