Skip to content

Tracking Order via WebSocket

After placing an order and submitting the deposit transaction, you can track the order until all outputs are finalized using the SilentSwap WebSocket API. The Core SDK provides trackOrderViaWebSocket, which connects to the API, subscribes to the order by orderId and viewingAuth, and resolves when every output reaches the FINALIZED stage.

When to use

  • After deposit: You have already placed an order and sent the deposit tx; you want to wait until the swap is fully completed (all outputs finalized).
  • Real-time updates: You want to show progress (e.g. bridge sent, bridge confirmed, finalized) in your UI or logs.
  • Scripts / backends: Node.js scripts (e.g. Solana swap script) that need to block until the order is done.

Requirements

  • orderId: Base58 order ID returned when you placed the order.
  • viewingAuth: Viewing authorization string. Obtain it from your facilitator group (e.g. facilitator_group_authorize_order_view or the viewer’s address encoded as Base58). The same viewer used in the quote request must be used here.
  • WebSocket: The function uses the global WebSocket (Node 18+ or browser). No extra dependency.

Basic usage

import {
  trackOrderViaWebSocket,
  getOrderTrackingWebSocketUrl,
  type OrderStatus,
  type OrderStatusUpdate,
} from '@silentswap/sdk';
 
// After you have orderId and viewingAuth from placing the order and facilitator group
const orderId = '...';      // Base58, from order response
const viewingAuth = '...';  // Base58, from facilitator group viewer
 
const finalStatus = await trackOrderViaWebSocket(orderId, viewingAuth);
 
console.log('Order completed:', finalStatus);
console.log('Deposit tx:', finalStatus.deposit.tx);
console.log('Outputs:', finalStatus.outputs.map((o) => ({ stage: o.stage, asset: o.asset, value: o.value })));

With options

You can pass a custom WebSocket URL, timeout, and an optional callback for each status update:

import {
  trackOrderViaWebSocket,
  getOrderTrackingWebSocketUrl,
  ENVIRONMENT,
  ENVIRONMENT_CONFIGS,
  type OrderStatusUpdate,
} from '@silentswap/sdk';
 
const orderId = '...';
const viewingAuth = '...';
 
// Optional: derive WS URL from API base URL (e.g. for staging)
const baseUrl = ENVIRONMENT_CONFIGS[ENVIRONMENT.STAGING].baseUrl;
const wsUrl = getOrderTrackingWebSocketUrl(baseUrl); // wss://api-staging.silentswap.com/websocket
 
const finalStatus = await trackOrderViaWebSocket(orderId, viewingAuth, {
  wsUrl,                    // default: wss://api.silentswap.com/websocket
  timeoutMs: 10 * 60 * 1000, // 10 minutes (default)
  onStatus: (update: OrderStatusUpdate) => {
    if (update.type === 'stage') {
      console.log('Stage:', update.data.stage, 'output index:', update.data.index);
    } else if (update.type === 'transaction') {
      console.log('Tx:', update.data.kind, update.data.chain, update.data.txId);
    } else if (update.type === 'deposit') {
      console.log('Deposit confirmed:', update.data.amount);
    } else if (update.type === 'error') {
      console.error('Order error:', update.data.message);
    }
  },
});

Return value

trackOrderViaWebSocket resolves with an OrderStatus object when all outputs have stage === 'FINALIZED'. The same structure is also sent in the WebSocket stream. It includes:

  • priority: Order priority / state label.
  • signer: Signer address.
  • deposit: { amount, duration, orderId, timestamp, tx } for the deposit.
  • outputs: Array of { stage, timestamp, asset, value, recipient, txs? }. stage progresses from NONE through INIT, FUNDED, REDEEMED, bridge stages, to FINALIZED. txs may contain RECEIPT or REFUND with chain and txId.

Errors and timeout

  • WebSocket not available: In older Node versions without global WebSocket, the function throws. Use Node 18+ or a browser.
  • Invalid auth: If orderId or viewingAuth are wrong, the server may respond with an error; the promise will reject.
  • Timeout: If the order is not fully finalized within timeoutMs (default 10 minutes), the promise rejects with "Order tracking timeout". You can increase timeoutMs for slow bridges.

Full flow example

Typical flow in a script (e.g. Solana swap):

  1. Authenticate and get facilitator group.
  2. Get quote, place order, get orderId and deposit params.
  3. Execute deposit (e.g. relay bridge or direct EVM deposit).
  4. Derive viewingAuth from the facilitator group (e.g. viewer’s EVM address as Base58).
  5. Call trackOrderViaWebSocket(orderId, viewingAuth) and await completion.
  6. Use finalStatus.outputs to show or log the final delivery details.
// 1–3: ... place order, execute deposit ...
 
// 4. Viewing auth from facilitator group (example: viewer EVM address as Base58)
const viewer = await facilitatorGroup.viewer();
const evmSigner = await viewer.evmSigner();
const viewingAuth = hexToBase58(evmSigner.address); // from @silentswap/sdk encoding
 
// 5. Track until finalized
const finalStatus = await trackOrderViaWebSocket(orderId, viewingAuth);
 
// 6. Done
console.log('All outputs finalized:', finalStatus.outputs.every((o) => o.stage === 'FINALIZED'));

Related