Skip to Content
WebsocketEvents

WebSocket Events

Message envelope

All business updates arrive on the Socket.IO event message with this shape (names match lib/types.ts in this repo and the SDK typings):

interface IntegrationWsMessageBaseData {
  externalUserId: string;
  integrationId: string;
  userId?: number | string;
}
 
interface IntegrationWsMessage<T = IntegrationWsMessageBaseData> {
  action: string;
  data: T;
}

Base fields on every data payload:

  • externalUserId — external user id from your system
  • integrationId
  • userId — optional (internal or external id depending on payload)

Payload types by action

Each action narrows data beyond the base fields. TypeScript names below are IntegrationWs* in lib/types.ts.

actiondata typeNotable fields
strategyUpdateIntegrationWsStrategyUpdateDatastrategyId, event (literal halted, resumed, or archived), strategy
swapIntegrationWsSwapDatastep (literal scheduled, executing, completed, or failed), swapId, chainId, optional type, amount, txSignature, balanceUpdated, error
depositStartIntegrationWsDepositStartDatadepositId, phase, chainId, chainType, depositAddress
depositStepIntegrationWsDepositStepDatastep (string); server may add more keys ([key: string]: unknown)
withdrawStartIntegrationWsWithdrawStartDatawithdrawId, phase, chainId, tokenAddress, amount, receiverAddress
withdrawStepIntegrationWsWithdrawStepDatastep (string); additional keys allowed
executionStepIntegrationWsExecutionStepDatastrategyId, step, chainId, type (buy or sell)

Listen for message

Use the same socket.io-client options as Connect — Client options (path, transports, reconnection, etc.).

Event streams are not available via plain curl. Use socket.io-client or the SDK (other tabs).

The polling probe on Connect only checks reachability, not business events.

Action catalog

The broadcaster emits message with action set to one of the IntegrationWsAction string literals:

  • strategyUpdate
  • swap
  • depositStart
  • depositStep
  • withdrawStart
  • withdrawStep
  • executionStep

Server-side emit shape: socket.to(integrationId).emit("message", { action, data }).

Typed handlers (SDK options)

The SDK maps each action to an optional typed callback:

Methodaction
onStrategyUpdatestrategyUpdate
onSwapswap
onDepositStartdepositStart
onDepositStepdepositStep
onWithdrawStartwithdrawStart
onWithdrawStepwithdrawStep
onExecutionStepexecutionStep
onAction(name, cb)custom action string
onMessage(cb)full envelope: action + data
socket.on("message", (msg) => {
  switch (msg.action) {
    case "swap":
      console.log("swap", msg.data.swapId, msg.data.step);
      break;
    case "executionStep":
      console.log("execution", msg.data.strategyId, msg.data.step);
      break;
    default:
      console.log(msg.action, msg.data);
  }
});

Unsubscribe

SDK handlers return an unsubscribe function:

const off = ws.onSwap((data) => {});
off();

With raw socket.io-client, use socket.off("message", handler) or keep a named handler reference.

ConnectReliability