WebSocket

Overview

The Atomic Vaults WebSocket endpoint provides real-time updates for order events. Connect to receive instant notifications when orders are filled, partially filled, replaced, or canceled.

Connection

Open a WebSocket connection to the appropriate environment. See Environments & Base URLs for the full list of WebSocket URLs across all markets.

Base URL Placeholder

Code examples on this page use {WS_BASE_URL} as a placeholder. Replace it with the WebSocket endpoint for your market and environment (e.g. wss://staging.atomicvaults.com). See Environments & Base URLs for all available endpoints.

Authentication is required via the X-API-KEY header when establishing the connection.

Example

const ws = new WebSocket("{WS_BASE_URL}/websocket", {
  headers: {
    "X-API-KEY": "your-api-key",
  },
});

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Event: ${data.message}, Order:`, data.order);
};

ws.onopen = () => {
  console.log("Connected to Atomic Vaults WebSocket");
};

ws.onclose = () => {
  console.log("Disconnected from Atomic Vaults WebSocket");
};

Message Format

Each message is a JSON object with the following structure:

{
  "message": "fill",
  "order": {
    "order_id": "abc123",
    "symbol": "AAPL",
    "side": "buy",
    "qty": "10",
    "filled_qty": "10",
    "status": "filled"
  }
}

Event Types

Event	Description
new	Order has been accepted
fill	Order has been completely filled
partial_fill	Order has been partially filled
replaced	Order has been modified/replaced
canceled	Order has been canceled

Multiple Connections

You may open multiple WebSocket connections simultaneously. Each connection receives the same set of order events for your account.

Reconnection

If the connection drops, implement automatic reconnection with exponential backoff:

function connect() {
  const ws = new WebSocket("{WS_BASE_URL}/websocket", {
    headers: { "X-API-KEY": "your-api-key" },
  });

  let retryDelay = 1000;

  ws.onclose = () => {
    setTimeout(() => {
      retryDelay = Math.min(retryDelay * 2, 30000);
      connect();
    }, retryDelay);
  };

  ws.onopen = () => {
    retryDelay = 1000;
  };

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    handleOrderEvent(data);
  };
}