Skip to Content
Symmio Trading-SDK — the SDK surface for builders on Arbitrum
ReactNotifications hooks

Notifications hooks

React hooks over the solver Notifications channel — a live WS stream plus a REST search over history.

Read-only page. useNotifications is a WebSocket subscription (still a “read” — no state mutation on-chain); useSearchNotifications is a REST-backed read.

The live stream (useNotifications) is protocol-agnostic: the underlying watchNotifications picks the resolved solver’s notifications protocol (enigma on Arbitrum, rasa on Base) and the hook API is identical either way. Pass solverId to target a non-default solver. See Solvers & Chains and the Notifications protocol axis.

TP/SL has its own separate WebSocket over the same underlying enigma service (different appName). See TP/SL.

Import

import {
  useNotifications,
  useSearchNotifications,
  type Notification,
  type NotificationType,
} from "@symmio/trading-react";

useNotifications

Subscribe to the live solver notifications WebSocket for one SubAccount. Returns the live socket status + delegates each parsed frame to your onNotification callback.

const { status } = useNotifications({
  account: subAccount,
  enabled: true,
  onNotification: (notification) => {
    console.log(notification.type, notification.quoteId, notification.lastSeenAction);
  },
});

Parameters

NameTypeDefaultNotes
accountAddress?undefinedSubAccount. When unset, the subscription is idle.
enabledboolean?trueGate the subscription behind a flag (e.g. live toggle).
chainIdnumber?config defaultOptional chain override.
solverIdSolverId?default solverTarget solver — selects the notifications endpoint + protocol.
onNotification(n: Notification) => void?undefinedFires per parsed frame.
onStatusChange(s: SocketStatus) => void?undefinedConnection status transitions.
onError(e: SymmError) => void?undefinedTransport / parse errors; does not stop the subscription.

Return type

{
  status: SocketStatus;
  error: SymmioRequestError | null;
}

Consumers reading the raw frames typically pass them into applyNotificationToQuotes (via useManagedQuotes) or into their own local reducer.

Connection pooling

Socket sharing follows the chain’s protocol. On enigma, every subscriber on the same (wsUrl, channel, account) triple shares one pooled connection; on rasa, every account on the same endpoint multiplexes onto a single hub socket. See Core watchNotifications and Core WebSocket.

useSearchNotifications

REST-backed paginated search over a solver’s notification history — one hook over both solver kinds, dispatched by the resolved solverId:

  • enigma → the standalone notification service (POST /api/v1/search), returning stored documents.
  • rasa → the solver’s own position-state endpoint (POST /position-state/{start}/{size}), returning position-state rows.

The result is a per-kind union — narrow on data.kind to read the variant’s rows.

const page = useSearchNotifications({
  account: subAccount,
  quoteId: 1024,
  start: 0,
  size: 20,
});
 
if (page.data?.kind === "enigma") page.data.rows.map((document) => document.id);
if (page.data?.kind === "rasa") page.data.rows.map((row) => row.quote_id);

The filters map per kind. tempQuoteId and the free-form filter are enigma-only; timestampGte is rasa-only; account / quoteId / start / size map on both. Pass a literal solverId (or narrow on data.kind) to reach a variant’s rows without casting.

Parameters

NameTypeNotes
solverIdSolverId?Target solver — selects the search endpoint + result variant. Defaults to chain’s.
accountAddress?Filter: counterparty (SubAccount) address.
quoteIdnumber?Filter: on-chain quote id.
tempQuoteIdnumber?Filter: pre-chain temporary quote id (negative). Enigma only.
timestampGtenumber?Filter: at/after this unix timestamp. Rasa only.
startnumber?Zero-based offset of the first row. Defaults to 0.
sizenumber?Max rows. Defaults to the endpoint default.
filterNotificationSearchFilter?Enigma-only advanced equality filter — top-level fields (app_name, …) or dotted data.* paths. Ignored for rasa.
baseUrlstring?Override the enigma notification-service base URL. Ignored for rasa.
chainIdnumber?Optional chain override.
queryobject?TanStack overrides.

Return type

UseQueryResult<NotificationSearchResult, SymmioRequestError> — the per-kind union. Narrow on data.kind:

  • kind: "enigma" → { total, count, rows } where rows are raw NotificationDocuments (their data payload is the wire frame), not normalized Notifications.
  • kind: "rasa" → { count, rows } where rows are PositionStateResponseSchema records.
  • Core Notifications — shape + enigma/rasa wire protocol.
  • Solvers & Chains — per-solver notifications protocol and the solver registry.
  • Unified Quotes — useManagedQuotes composes useNotifications under the hood.
  • TP/SL — separate WS + REST for conditional-order reports.
Last updated on
Candles hooksSubgraph hooks