Order Updates WebSocket

There are two ways to follow an order after you place it:

The WebSocket is read-only. You still place and cancel orders with the REST API. The only message you send over the connection is the heartbeat described in Keeping the connection open.

The WebSocket is served on the same host as the REST API: wss://api.public.com.

• Authentication. An OAuth2 bearer token with the trading.read scope, the same token you use for the REST API. Placing orders still needs trading.write, but receiving events does not.
• Account. The account numbers you subscribe to must belong to the user the token was issued for. Get them from Get accounts. The accountId of each returned account is the account number to use here, for example 5RE12345.
• A client that can set request headers. The token is sent in the Authorization header of the handshake. Browsers cannot set headers on a WebSocket, so connect from a server-side client. Do not put the token in the URL.

wss://api.public.com/userapigateway?accountIds={accounts}&channels={channels}

GET /userapigateway?accountIds=5RE12345&channels=order
Authorization: Bearer <token>
Upgrade: websocket
Connection: Upgrade

Your WebSocket library sends the upgrade headers. You supply the URL and the Authorization header. The path has no version number: a future version of this API will be selected by you when you connect.

Query parameters

accountIds=* stands for the accounts the user has at the moment of connecting. An account opened later is not added to the open connection: reconnect to receive its events.

Example: wscat

npx wscat \
  -c "wss://api.public.com/userapigateway?accountIds=5RE12345&channels=order" \
  -H "Authorization: Bearer $TOKEN"

Example: Node.js

import WebSocket from "ws";

const url = "wss://api.public.com/userapigateway?accountIds=5RE12345&channels=order";
const socket = new WebSocket(url, { headers: { Authorization: `Bearer ${token}` } });

let heartbeat;

socket.on("open", () => {
  console.log("connected");
  heartbeat = setInterval(() => socket.send(JSON.stringify({ action: "ping" })), 60_000);
});

socket.on("message", (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === "ORDER_UPDATE") {
    handleOrder(event.payload.order);
  }
  // Ignore every other type: new event types can be added without notice.
});

socket.on("close", () => {
  clearInterval(heartbeat);
  // Reconnect with a fresh token and backoff, then reload state from the REST API.
});

socket.on("unexpected-response", (_request, response) => {
  console.error("rejected with HTTP", response.statusCode);
});

What a successful connection looks like

The handshake completes with HTTP 101 and the server sends nothing until the first order changes. There is no welcome message. A connection that is rejected never upgrades: your client sees an HTTP error status on the handshake. See Errors.

An idle connection is closed after 10 minutes, and any connection is closed after 2 hours at the latest, even when it is busy. Send a heartbeat to stay under the idle limit, and reconnect when the connection closes.

Send this text message:

{"action":"ping"}

and you receive:

{"type":"PONG"}

Any message you send resets the idle timer. No other message is supported, so do not send anything else.

The token is checked only when you connect. An open connection stays open after the token expires, until the 2 hour limit closes it. When you reconnect, use a fresh token.

The frame

Every message pushed to you is a JSON text frame with the same four fields:

{
  "channel": "order",
  "type": "ORDER_UPDATE",
  "payload": { "order": { ... } },
  "timestamp": "2026-10-28T20:00:00Z"
}

ORDER_UPDATE

Sent every time an order changes: when it is accepted, partially filled, filled, cancelled, rejected, expired, or replaced. The payload has a single field, order, which is the complete order after the change, not the difference from the previous event. Use version to order the events of an order. See Behavior to design around.

You receive the events of the accounts you subscribed to. Delivery is best-effort.

The order object

The order has the same shape as the orders in the orders list of Get account portfolio v2. It is not identical to the order returned by the order endpoints. See REST orders vs. WebSocket orders. Optional fields are null or absent when they do not apply.

Example: new limit order

{
  "channel": "order",
  "type": "ORDER_UPDATE",
  "payload": {
    "order": {
      "orderId": "0b0b6a6e-6a41-4b5b-9d33-0d9c6a3a8f10",
      "accountNumber": "5RE12345",
      "version": 1,
      "instrument": { "symbol": "AAPL", "type": "EQUITY" },
      "type": "LIMIT",
      "side": "BUY",
      "status": "NEW",
      "quantity": 10,
      "expiration": { "timeInForce": "DAY", "expirationTime": null },
      "limitPrice": 180.00,
      "session": "CORE",
      "effective": true,
      "editable": true,
      "cancellable": true,
      "createdAt": "2026-10-28T20:00:00Z",
      "lastModified": "2026-10-28T20:00:00Z"
    }
  },
  "timestamp": "2026-10-28T20:00:00.120Z"
}

Example: the same order, filled

{
  "channel": "order",
  "type": "ORDER_UPDATE",
  "payload": {
    "order": {
      "orderId": "0b0b6a6e-6a41-4b5b-9d33-0d9c6a3a8f10",
      "accountNumber": "5RE12345",
      "version": 3,
      "instrument": { "symbol": "AAPL", "type": "EQUITY" },
      "type": "LIMIT",
      "side": "BUY",
      "status": "FILLED",
      "quantity": 10,
      "expiration": { "timeInForce": "DAY", "expirationTime": null },
      "limitPrice": 180.00,
      "session": "CORE",
      "filledQuantity": 10,
      "averagePrice": 179.85,
      "effective": true,
      "editable": false,
      "cancellable": false,
      "createdAt": "2026-10-28T20:00:00Z",
      "lastModified": "2026-10-28T20:00:02Z"
    }
  },
  "timestamp": "2026-10-28T20:00:02.150Z"
}

1. Get a token with the trading.read scope and list the accounts with Get accounts.
2. Open the WebSocket for the accounts and the order channel. Start reading events immediately and buffer them.
3. Load the current state from the REST API. Get account portfolio v2 returns the open orders in the same shape as the events, and Search orders returns orders created in the last 30 days, up to 500 per call.
4. Merge the buffered events into the loaded state and keep applying new events. For each orderId, keep the order with the highest version.
5. Send {"action":"ping"} every 60 seconds.
6. When the connection closes, for any reason, reconnect with a fresh token and repeat from step 2. Do not assume you saw every event while you were disconnected.

The order endpoints (Get order and Search orders) return a slightly different order than the WebSocket. They include closedAt, filledAt, and trades, call the session equityMarketSession, and have no version, accountNumber, effective, editable, or cancellable.

At-most-once, no replay

An event is posted to the connections that are open at that moment. If you are disconnected, or an event cannot be delivered, it is not retried and not replayed when you reconnect.

Events can be repeated

The events of an order are published in order. After a restart on the server side, events that were already sent can be sent again, including older versions of an order you already have a newer version of. Each event carries the complete order, so you never need to merge fields.

One event per state, not per trade

Every change of an order gives it a new version and produces one event with the complete order after that change, so a partial fill is one event and the next partial fill is another. The exception is a multi-leg order: executions on the individual legs do not change the order until the legs are balanced, so they are reported together in one event. Order events do not list individual trades. Subscribe to the trade channel of the Trades WebSocket to receive each trade, or use Get order. Order and trade events are delivered independently, so do not expect one to arrive before the other.

Be liberal in what you accept

Fields, enum values, event types, and channels can be added without notice. Ignore fields you do not know, ignore event types you do not handle, and do not fail on an enum value you have not seen. Do not depend on the order of the fields in the JSON.

Subscriptions are fixed per connection

The accounts and channels are chosen in the URL when you connect. You cannot add or remove them on an open connection. To change them, open a new connection and close the old one.

Several accounts on one connection

One connection can carry several accounts. It counts as one of the connections of each of those accounts. See Limits. Use accountNumber in the order to tell the accounts apart.

Authorization is checked when you connect

If the user loses access to an account while a connection is open, the connection keeps receiving that account's events until it is closed or reaches the 2 hour limit. Reconnect regularly rather than relying on a connection to enforce access.

Reconnect with backoff

A rejected handshake returns an HTTP status instead of upgrading. The body is a short plain-text message and is not meant to be parsed: rely on the status.

After the connection is open, the server can close it at any time, including at the 2 hour limit and for idle timeouts. Treat every close as a reason to reconnect.

Opening a connection makes one request to the REST API on your behalf to check your token and accounts. The REST rate limits (per client, shared across all endpoints) apply to your REST calls as usual. On a 429 from a REST call, back off and retry.