Trades WebSocket

A trade is one execution: a quantity at a price on a side, for one instrument, in one account. An order that fills in three parts produces three trades. The Trades WebSocket pushes each trade to you as it is recorded, and again if it is cancelled.

Trades are one channel of the Public API WebSocket. The other is the order channel, documented in Order Updates WebSocket. A connection receives only the channels it subscribes to:

Subscribe with channels=order,trade to receive both on one connection. The WebSocket is read-only, and trades do not include fees or commissions. For those, use Get history once the transaction posts.

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.
• 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 and relay to the browser yourself if you need to. Do not put the token in the URL.

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

GET /userapigateway?accountIds=5RE12345&channels=trade
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

Duplicates in either list are ignored. There is no default subscription: a connection without accountIds or channels is rejected. 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 trades.

Example: wscat

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

Example: Node.js

import WebSocket from "ws";

const url = "wss://api.public.com/userapigateway?accountIds=5RE12345&channels=trade";
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.channel === "trade" && event.type === "TRADE") {
    handleTrade(event.payload);
  }
  // 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 next trade in one of the accounts. 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. An account can go much longer than 10 minutes without a trade, so 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, on every channel:

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

TRADE

Sent when a trade is recorded in one of the accounts you subscribed to, and again with the same tradeId if the trade is cancelled. Unlike ORDER_UPDATE, the payload is the trade itself, not wrapped in another object.

The trade object

The trade has the fields of the trades in the trades array of Get order, plus orderId, originalTradeId, accountNumber, and status. Nullable fields are always present, with the value null when they do not apply.

instrument.type is one of:

EQUITY · OPTION · MULTI_LEG_INSTRUMENT · CRYPTO · ALT · TREASURY · BOND · INDEX · EVENTCONTRACT

The symbol is the one you use in REST requests: BTC, not BTC-CRYPTO, and AAPL251219C00150000, not AAPL251219C00150000-OPTION. The kind of instrument is in instrument.type. Trades in instruments the Public API does not support are not published.

Example: equity

A whole share bought on a venue that reported its market code.

{
  "channel": "trade",
  "type": "TRADE",
  "payload": {
    "tradeId": "T-1",
    "orderId": "0b0b6a6e-6a41-4b5b-9d33-0d9c6a3a8f10",
    "originalTradeId": null,
    "accountNumber": "5RE12345",
    "status": "NEW",
    "instrument": { "symbol": "AAPL", "type": "EQUITY" },
    "quantity": "1",
    "price": "170.00",
    "side": "BUY",
    "timestamp": "2026-10-28T19:59:59Z",
    "marketIdentificationCode": "XNAS"
  },
  "timestamp": "2026-10-28T20:00:00Z"
}

Example: option

Two contracts sold. The symbol has no -OPTION suffix and the venue did not report a market code.

{
  "channel": "trade",
  "type": "TRADE",
  "payload": {
    "tradeId": "T-2",
    "orderId": "5d2c7a0e-1f64-4d0b-8a0f-6c3b2f9e41aa",
    "originalTradeId": null,
    "accountNumber": "5RE12345",
    "status": "NEW",
    "instrument": { "symbol": "AAPL251219C00150000", "type": "OPTION" },
    "quantity": "2",
    "price": "4.35",
    "side": "SELL",
    "timestamp": "2026-10-28T15:12:03Z",
    "marketIdentificationCode": null
  },
  "timestamp": "2026-10-28T15:12:03Z"
}

Example: crypto

A fractional quantity. Decimals stay strings, so no precision is lost.

{
  "channel": "trade",
  "type": "TRADE",
  "payload": {
    "tradeId": "T-3",
    "orderId": "9a3f1e55-2b7c-4c9d-9e11-0d4f6a7b8c90",
    "originalTradeId": null,
    "accountNumber": "5RE12345",
    "status": "NEW",
    "instrument": { "symbol": "BTC", "type": "CRYPTO" },
    "quantity": "0.5",
    "price": "65000.10",
    "side": "BUY",
    "timestamp": "2026-10-28T19:59:59Z",
    "marketIdentificationCode": null
  },
  "timestamp": "2026-10-28T20:00:01Z"
}

Example: cancelled trade

The equity trade above, taken back. Same tradeId, status now CANCELLED. The rest of the payload repeats the trade.

{
  "channel": "trade",
  "type": "TRADE",
  "payload": {
    "tradeId": "T-1",
    "orderId": "0b0b6a6e-6a41-4b5b-9d33-0d9c6a3a8f10",
    "originalTradeId": null,
    "accountNumber": "5RE12345",
    "status": "CANCELLED",
    "instrument": { "symbol": "AAPL", "type": "EQUITY" },
    "quantity": "1",
    "price": "170.00",
    "side": "BUY",
    "timestamp": "2026-10-28T19:59:59Z",
    "marketIdentificationCode": "XNAS"
  },
  "timestamp": "2026-10-29T08:30:00Z"
}

Example: trade without an order

A trade that does not belong to an order. orderId is null.

{
  "channel": "trade",
  "type": "TRADE",
  "payload": {
    "tradeId": "A-77",
    "orderId": null,
    "originalTradeId": null,
    "accountNumber": "5RE12345",
    "status": "NEW",
    "instrument": { "symbol": "AAPL", "type": "EQUITY" },
    "quantity": "3",
    "price": "168.40",
    "side": "BUY",
    "timestamp": "2026-10-28T14:00:00Z",
    "marketIdentificationCode": null
  },
  "timestamp": "2026-10-28T14:00:02Z"
}

A trade that corrects an earlier trade has the ID of the earlier trade in originalTradeId. Corrections and cancellations are rare, but handle both: the fields are always in the payload.

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 trade channel (and order, if you use it). Start reading events immediately and buffer them.
3. Once the connection is open, load the current state from the REST API. Search orders returns orders created in the last 30 days, up to 500 per call, each with its trades. Get order returns one order with its trades. Store the trades by tradeId.
4. Apply the buffered events in the order received, then keep applying new events as they arrive. The latest event per tradeId wins.
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 trade while you were disconnected.

Buffering first and reading second closes the gap between the two: a trade recorded while you read the REST API is in the buffer, and applying it on top of the REST state is harmless. Load the REST state after the connection is open, not before: a trade recorded in the instant right after you connect can otherwise be missed.

Trades returned by the REST API have no status, orderId, or accountNumber field. Treat them as NEW trades of the order and account you read them from, and let events update them.

Example: a complete client in Node.js

A skeleton with the ws package (Node.js 20 or later) that buffers, loads, and reconnects. The REST call is left for you to fill in.

import WebSocket from "ws";

const URL = "wss://api.public.com/userapigateway?accountIds=5RE12345&channels=trade";
const PING_EVERY_MS = 60_000;          // idle connections are closed after 10 minutes
const MAX_BACKOFF_MS = 30_000;
const FATAL = new Set([400, 401, 403]); // do not retry these unchanged

// The latest known state per tradeId. A later frame replaces an earlier one.
const trades = new Map();

function applyFrame(frame) {
  if (frame.channel !== "trade" || frame.type !== "TRADE") {
    return; // ignore PONG and every channel and type this client does not know
  }
  trades.set(frame.payload.tradeId, frame.payload);
}

async function loadTradesFromRest() {
  // Call Search orders for the account and put the trades of every order in `trades`.
}

export function connect(getToken, attempt = 0) {
  const ws = new WebSocket(URL, { headers: { Authorization: `Bearer ${getToken()}` } });
  let buffered = [];   // frames that arrive while the REST state is loading
  let live = false;
  let rejectedWith;    // the HTTP status of a rejected handshake
  let pingTimer;

  ws.on("open", async () => {
    attempt = 0;
    pingTimer = setInterval(() => ws.send(JSON.stringify({ action: "ping" })), PING_EVERY_MS);
    try {
      await loadTradesFromRest();
    } catch (error) {
      console.error("Could not load the trades, reconnecting:", error.message);
      ws.terminate(); // do not go live on partial state
      return;
    }
    buffered.forEach(applyFrame);
    buffered = [];
    live = true;
  });

  ws.on("message", (data) => {
    const frame = JSON.parse(data.toString());
    if (live) applyFrame(frame); else buffered.push(frame);
  });

  ws.on("unexpected-response", (_request, response) => {
    rejectedWith = response.statusCode;
    response.resume();
    ws.terminate(); // ends in "close"
  });

  ws.on("error", (error) => console.error("WebSocket error:", error.message));

  ws.on("close", () => {
    clearInterval(pingTimer);
    if (FATAL.has(rejectedWith)) {
      console.error(`Connection rejected with ${rejectedWith}, not retrying`);
      return;
    }
    // Exponential backoff with jitter. 429, 500, and 503 end up here as well.
    const delay = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt) * (0.5 + Math.random() / 2);
    setTimeout(() => connect(getToken, attempt + 1), delay);
  });

  return ws;
}

At-most-once, no replay

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

Apply events idempotently

An event with the same tradeId and status as one you already have changes nothing, which comes for free when the latest event per tradeId wins. If you hold more than one connection for an account, each connection receives every trade.

Ordering

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 trade 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 trades 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.