Skip to main content

WebSocket

Overview​

The order-update WebSocket pushes a message every time one of your orders changes: when it is accepted, filled, replaced, canceled or rejected. Use it to keep order state current without polling, and use the REST order endpoints to recover anything you missed while disconnected.

Each market has its own WebSocket. A connection only carries updates for orders in the market it belongs to.

Endpoints​

MarketWebSocket URLOrder endpoints to reconcile with
USwss://{US_HOST}/websocketGET /orders, GET /orders/status
HKwss://{APAC_HOST}/websocketGET /orders, GET /orders/status
KR (beta)wss://{APAC_HOST}/kr/websocketGET /kr/orders, GET /kr/orders/status
TW (beta)wss://{APAC_HOST}/tw/websocketGET /tw/orders, GET /tw/orders/status

{US_HOST} and {APAC_HOST} are the hostnames of your environment, for example uat.atomicvaults.com or apac.uat.atomicvaults.com. See Environments & Base URLs for the full list.

Connecting​

  • Authentication. Send your X-API-KEY header on the upgrade request. The key is checked before the upgrade: a missing or invalid key gets an HTTP 401 error response instead of a WebSocket.
  • Connect from your server. Browsers cannot set custom headers on a WebSocket, so open the connection from your backend and fan updates out to your own clients.
  • Server to client only. The server does not expect any messages from you. Don't send data frames; the connection may be closed if you do.
  • Keepalive. The server sends a WebSocket ping every 30 seconds. Standard client libraries answer pings automatically.
  • Multiple connections. You can open several connections with the same key. Every connection receives every update.
  • Read promptly. Each connection buffers up to 1,000 messages. If your client falls further behind, later messages for that connection are dropped. (HK, KR and TW.)

Which Updates You Receive​

A connection receives updates for the orders of the API client that owns the key, across all of that client's accounts in the market. In HK, KR and TW, updates follow the order's receiving_initiator: if you place an order with receiving_initiator set to another client, that client's connections receive the updates instead.

Message Format​

Every message is a JSON text frame with the same envelope:

{
"message_type": "order_update",
"message": {
"order_event": "partial_fill",
"order": { "...": "the full order, same shape as GET /orders/status" },
"last_qty": "4",
"last_px": "70000",
"timestamp": "2026-11-06T01:16:03.402117Z"
}
}
FieldDescription
message_typeAlways order_update. Ignore message types you don't recognise so new types can be added safely.
message.order_eventWhat happened. See Order Events.
message.orderThe order after the event, in the same shape the order-status endpoint returns for that market.
message.last_qtyQuantity of this fill. Present only for partial_fill and fill.
message.last_pxPrice of this fill. Present only for partial_fill and fill.
message.timestampWhen the event was recorded, in UTC.
message.textReason for a rejection, cancellation or failed request, formatted as <error_code>: <message>. Absent when there is no reason.

Numeric values such as quantities and prices are strings, to keep decimal precision.

Order Events​

These events are sent in every market:

EventDescription
newAtomic Vaults accepted the order. It is sent before the exchange acknowledges the order.
partial_fillPart of the order filled. last_qty and last_px describe this fill.
fillThe order is completely filled. last_qty and last_px describe the final fill.
canceledThe order was canceled: on your request, when it expired at the end of its session, or by the venue.
rejectedThe order was rejected after it was accepted, by a risk check or by the venue. text gives the reason.
replacedA modify completed. order is the replacement order: its order_id is the replacement_order_id you sent and its orig_order_id is the order it replaced. The replaced order does not get a separate update.
cancel_rejectedA cancel request failed. order is the order you tried to cancel, which is still working.
replace_rejectedA modify failed. The original order stays working.

When a request fails with an HTTP error (a 400 from orders/new, for example), treat the HTTP response as the result. Most of these failures send no WebSocket update. Some order rejections from risk checks, such as insufficient cash, can also arrive as a rejected update.

US

The US WebSocket can also send stopped, and adds overnight-option fields (overnight_cum_qty, overnight_avg_px, is_opening_fill, is_final_opening_fill) and end_of_trading. See the US WebSocket reference.

Example​

A Korean limit buy for 10 shares of 005930 that fills in two parts produces three messages: new, then partial_fill (4 shares), then fill. This is the final one:

{
"message_type": "order_update",
"message": {
"order_event": "fill",
"order": {
"av_order_id": "3f1c2b8e-6a0d-4e57-9b1f-2d4c8a7e5b90",
"order_id": "kr-equity-001",
"quantity": "10",
"quantity_filled": "10",
"notional": null,
"notional_filled": "699400",
"average_price": "69940",
"order_type": "limit",
"limit_price": "70000",
"position_effect": "open",
"side": "buy",
"status": "filled",
"symbol": "005930",
"security_type": "CS",
"market": "KR",
"time_placed": "2026-11-06T01:15:42.123456Z",
"order_completion_time": "2026-11-06T01:16:10.551203Z",
"initiator": "CUST1",
"time_in_force": "day"
},
"last_qty": "6",
"last_px": "69900",
"timestamp": "2026-11-06T01:16:10.558912Z"
}
}

Each market's API reference has example messages for every event: HK, KR, TW, US.

Missed Updates and Reconnection​

Updates are delivered only to connections that are open when the event happens. Nothing is replayed when you reconnect. To stay in sync:

  1. Reconnect with exponential backoff when the connection drops.
  2. After reconnecting, call the market's GET /orders endpoint for the period you were disconnected, and update any order whose status changed.
  3. Treat the REST response as the source of truth if it disagrees with what you saw on the WebSocket.

Node.js​

Uses the ws package.

import WebSocket from "ws";

const URL = "wss://{APAC_HOST}/kr/websocket"; // pick the URL for your market
let retryDelay = 1000;

function connect() {
const ws = new WebSocket(URL, {
headers: { "X-API-KEY": process.env.AV_API_KEY },
});

ws.on("open", () => {
retryDelay = 1000;
reconcileOrders(); // GET /kr/orders for the time you were offline
});

ws.on("message", (data) => {
const frame = JSON.parse(data.toString());
if (frame.message_type !== "order_update") return;
const { order_event, order, last_qty, last_px } = frame.message;
handleOrderEvent(order_event, order, last_qty, last_px);
});

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

ws.on("error", () => ws.close());
}

connect();

Python​

Uses the websockets package (version 14 or later).

import asyncio
import json
import os

import websockets

URL = "wss://{APAC_HOST}/kr/websocket" # pick the URL for your market


async def run():
async for ws in websockets.connect(
URL, additional_headers={"X-API-KEY": os.environ["AV_API_KEY"]}
): # reconnects with backoff
try:
await reconcile_orders() # GET /kr/orders for the time you were offline
async for raw in ws:
frame = json.loads(raw)
if frame["message_type"] != "order_update":
continue
handle_order_event(frame["message"])
except websockets.ConnectionClosed:
continue


asyncio.run(run())