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
| Market | WebSocket URL | Order endpoints to reconcile with |
|---|---|---|
| US | wss://{US_HOST}/websocket | GET /orders, GET /orders/status |
| HK | wss://{APAC_HOST}/websocket | GET /orders, GET /orders/status |
| KR (beta) | wss://{APAC_HOST}/kr/websocket | GET /kr/orders, GET /kr/orders/status |
| TW (beta) | wss://{APAC_HOST}/tw/websocket | GET /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-KEYheader on the upgrade request. The key is checked before the upgrade: a missing or invalid key gets an HTTP401error 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"
}
}
| Field | Description |
|---|---|
message_type | Always order_update. Ignore message types you don't recognise so new types can be added safely. |
message.order_event | What happened. See Order Events. |
message.order | The order after the event, in the same shape the order-status endpoint returns for that market. |
message.last_qty | Quantity of this fill. Present only for partial_fill and fill. |
message.last_px | Price of this fill. Present only for partial_fill and fill. |
message.timestamp | When the event was recorded, in UTC. |
message.text | Reason 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:
| Event | Description |
|---|---|
new | Atomic Vaults accepted the order. It is sent before the exchange acknowledges the order. |
partial_fill | Part of the order filled. last_qty and last_px describe this fill. |
fill | The order is completely filled. last_qty and last_px describe the final fill. |
canceled | The order was canceled: on your request, when it expired at the end of its session, or by the venue. |
rejected | The order was rejected after it was accepted, by a risk check or by the venue. text gives the reason. |
replaced | A 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_rejected | A cancel request failed. order is the order you tried to cancel, which is still working. |
replace_rejected | A 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.
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:
- Reconnect with exponential backoff when the connection drops.
- After reconnecting, call the market's
GET /ordersendpoint for the period you were disconnected, and update any order whose status changed. - 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())