WebSocket Connect

The integration WebSocket uses Socket.IO (not raw WebSockets). Clients should use socket.io-client or the IntegrationWsClient SDK.

Endpoint

Setting	Value
Origin	`https://ws.partners.sonar.trade`
Socket.IO `path`	`/ws`

Pass the origin only to io() — the path is set separately via the path option (see below). The SDK accepts a full URL such as https://partners.sonar.trade/ws and splits origin + pathname (/ws).

Client options (`socket.io-client`)

When calling io(url, options), common options:

Option	Example	Notes
`path`	`"/ws"`	Required. Must match the server (`path: "/ws"`).
`transports`	`["websocket", "polling"]`	Try WebSocket first, fall back to HTTP long-polling. Use `["websocket"]` only if you forbid polling.
`reconnection`	`true`	Auto-reconnect (default `true`).
`reconnectionAttempts`	`10`	Max attempts before giving up (`Infinity` = no cap).
`reconnectionDelay`	`1000`	Initial delay before reconnect (ms).
`reconnectionDelayMax`	`5000`	Max delay between attempts (ms).
`timeout`	`20000`	Connection timeout (ms).

Server-side CORS is configured on the integration app; browser clients must use an allowed origin.

SDK

IntegrationWsClient accepts wsUrl, apiKey, and apiSecret only. It connects with path derived from wsUrl and transports: ["websocket", "polling"]. To tune reconnection, timeout, etc., use socket.io-client directly (Node.js tab) or wrap the SDK.

Auth handshake

After the Socket.IO connection succeeds, the client must emit:

Event: authenticate
Payload: JSON object with apiKey and secret (strings; trimmed on the server)

The server responds with one of:

authenticated — payload includes integrationId
error — payload includes code and message (e.g. AUTH_REQUIRED, AUTH_FAILED)

Connect and authenticate

curl

Socket.IO is not a simple REST resource — curl cannot join a Socket.IO session or emit authenticate / receive message the way a client library does.

Optional — Engine.IO polling probe (connectivity / version check; response shape varies):


curl -sS "https://partners.sonar.trade/ws/?EIO=4&transport=polling"

Use Node.js or the SDK for real connections.

Node.js


import { io } from "socket.io-client";
 
const socket = io("https://partners.sonar.trade", {
  path: "/ws",
  transports: ["websocket", "polling"],
  reconnection: true,
  reconnectionAttempts: 10,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
  timeout: 20000,
});
 
socket.on("connect", () => {
  socket.emit("authenticate", {
    apiKey: process.env.SONAR_API_KEY,
    secret: process.env.SONAR_API_SECRET,
  });
});
 
socket.on("authenticated", (payload) => {
  console.log("authenticated", payload.integrationId);
});
 
socket.on("error", (err) => {
  console.error("auth error", err.code, err.message);
});
 
socket.on("connect_error", (err) => {
  console.error("network error", err);
});

On each connect (including reconnect), emit authenticate again. Listen for error (auth) vs connect_error (transport).

SDK


import { IntegrationWsClient } from "@sonar/api-sdk";
 
const ws = new IntegrationWsClient({
  wsUrl: "https://partners.sonar.trade/ws",
  apiKey: process.env.SONAR_API_KEY!,
  apiSecret: process.env.SONAR_API_SECRET!,
});
 
await ws.connect();

Register handlers

See Events for message payloads and typed SDK helpers.


const unsubscribeSwap = ws.onSwap((data) => {
  console.log("swap update", data.swapId, data.step);
});
 
const unsubscribeDeposit = ws.onDepositStep((data) => {
  console.log("deposit step", data.step);
});

Disconnect


unsubscribeSwap();
unsubscribeDeposit();
ws.disconnect();