Quickstart

This guide takes you from your API key to a live, gap-free orderbook in one connection. The examples are Node.js with the ws library, but the protocol is plain JSON over a standard WebSocket, so you can use any WebSocket client.

Prerequisites

Your ParlayX API key, the same signed Ed25519 key you use for REST. See Authentication.
One or more MarketStream values for the markets you want. See identifying markets.

1. Connect and authenticate

Sign the handshake with your private key and put the credentials on the query string of:

wss://wss.parlayx.com/v1/orderbook

Authentication happens during the WebSocket upgrade. There is no separate login message. Sign the canonical handshake string with your Ed25519 key (see Authentication for the full contract) and put the credentials on the query string:

import WebSocket from "ws";
import { createHash, createPrivateKey, sign } from "node:crypto";

const keyId = process.env.PARLAYX_KEY_ID;
const timestamp = Math.floor(Date.now() / 1000).toString();

const der = Buffer.concat([
  Buffer.from("302e020100300506032b657004220420", "hex"),
  Buffer.from(process.env.PARLAYX_PRIVATE_KEY_HEX, "hex"),
]);
const privateKey = createPrivateKey({ key: der, format: "der", type: "pkcs8" });
const emptyBodyHash = createHash("sha256").update("").digest("hex");
const canonical = ["WS", "/v1/orderbook", "", timestamp, emptyBodyHash].join("\n");
const signature = sign(null, Buffer.from(canonical), privateKey).toString("hex");

const ws = new WebSocket(
  `wss://wss.parlayx.com/v1/orderbook?keyId=${keyId}&timestamp=${timestamp}&signature=${signature}`,
);

If the credentials are missing or the signature is invalid, the upgrade is rejected with HTTP 401 before the connection opens. A 503 means the gateway is at capacity: reconnect, and you’ll land on fresh capacity. A 429 means your account is at its connection limit, so close a connection you no longer need instead of retrying.

2. Receive `WELCOME`

Immediately after the upgrade succeeds, the server sends a WELCOME frame:

{
  "type": "WELCOME",
  "v": 1,
  "serverTimestamp": 1748020034123,
  "credentialId": "9a4b7e2c-1a64-4dca-9d6e-1b8c2d3f4a5b",
  "connectionId": "1d3a9c44-cf21-4f33-9211-2b9b1adf67e8",
  "activeConnections": 1,
  "limits": { "maxSubscriptionsPerConnection": 200, "maxConnections": 20, "connectionTtlSeconds": 28800 }
}

Keep the connectionId, and quote it in any support request so we can find your session in our logs. The limits tell you how many subscriptions this connection accepts and how long it will live before the server closes it for a scheduled reconnect. Send a SUBSCRIBE frame listing the markets you want. The only required fields are type and markets; channels defaults to ["BOOK"].

ws.on("open", () => {
  // Wait for `WELCOME`, then subscribe. See the message handler below.
});

function subscribe(ws) {
  ws.send(JSON.stringify({
    type: "SUBSCRIBE",
    requestId: "01HZX0RJQ4Z6K7Y9V2N0WP3M8C",  // optional correlation token
    markets: [
      { venue: "POLYMARKET", tokenId: "71045620195867637" },
      { venue: "KALSHI", ticker: "KXNBA-25-LAL" },
      // A ProphetX strikeId names the market and the outcome at once, so the
      // other outcome is a separate strike with its own id.
      { venue: "PROPHETX", strikeId: "ab39fb9a7b4eb6a26d7e26f885c601c1" },
      // Limitless outcomeId is the outcome token id from market discovery,
      // these two entries are the slug's YES and NO tokens.
      { venue: "LIMITLESS", kind: "CLOB", marketId: "btc-100k-weekly", outcomeId: "84329471234058196" },
      { venue: "LIMITLESS", kind: "CLOB", marketId: "btc-100k-weekly", outcomeId: "97318264051273948" },
    ],
  }));
}

For each market in the batch you get back a SUBSCRIBED ack or an ERROR (for example, UNKNOWN_MARKET), so a market the server cannot resolve never sinks the rest of the batch. SUBSCRIBED is sent before the upstream venue feed has confirmed the market. If the feed then refuses it or does not confirm it in time, or a book’s first snapshot never arrives, a later ERROR carrying the subscriptionId ends the subscription, so one market can get a SUBSCRIBED followed by an ERROR. See ERROR. A frame that fails validation is different: the whole frame is rejected before any market is read, so a malformed entry takes its batch with it.

{
  "type": "SUBSCRIBED",
  "v": 1,
  "serverTimestamp": 1748020034200,
  "market": { "venue": "POLYMARKET", "tokenId": "71045620195867637" },
  "channel": "BOOK",
  "subscriptionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "snapshotPending": true
}

Cache the mapping from subscriptionId to whatever local state you keep for that market. Every subsequent frame for this subscription is keyed by that id, and it’s also the handle you pass to unsubscribe. snapshotPending: true tells you a SNAPSHOT is on its way.

4. Apply the stream

A book subscription delivers a SNAPSHOT first, then DELTA frames:

const books = new Map();        // subscriptionId -> { bids, asks }
const lastSeq = new Map();      // subscriptionId -> last seq seen

ws.on("message", (raw) => {
  const f = JSON.parse(raw.toString());
  switch (f.type) {
    case "WELCOME":
      subscribe(ws);
      break;

    case "SNAPSHOT":
      // Replace local state wholesale.
      books.set(f.subscriptionId, { bids: f.bids, asks: f.asks });
      lastSeq.set(f.subscriptionId, f.seq);
      break;

    case "DELTA": {
      // Apply each change; size 0 deletes the level.
      const book = books.get(f.subscriptionId);
      if (!book) break;
      for (const c of f.changes) {
        const side = c.side === "BID" ? book.bids : book.asks;
        const i = side.findIndex((l) => l.price === c.price);
        if (c.size === 0) { if (i >= 0) side.splice(i, 1); }
        else if (i >= 0) side[i].size = c.size;
        else side.push({ price: c.price, size: c.size });
      }
      lastSeq.set(f.subscriptionId, f.seq);
      break;
    }

    case "STATUS":
      // e.g. "RESYNCING". See the reconnect/resync guide.
      break;

    case "ERROR":
      console.error("stream error", f.code, f.message);
      break;
  }
});

That’s the whole opening sequence. SNAPSHOT replaces your book; DELTA mutates it. Because of the sequencing contract, your apply loop needs no gap-handling logic of its own. If we ever could not send a contiguous delta, we send a fresh SNAPSHOT instead.

Optional: the trade tape

To also receive each fill on a market as it executes, subscribe with the TRADE channel (each (market, channel) pair is its own subscription, with its own subscriptionId):

ws.send(JSON.stringify({
  type: "SUBSCRIBE",
  markets: [{ venue: "POLYMARKET", tokenId: "71045620195867637" }],
  channels: ["BOOK", "TRADE"],   // or ["TRADE"] for the tape alone
}));

Then add a case to the handler:

    case "TRADE":
      // One frame per fill: price, size, and the taker (aggressor) side.
      console.log(f.subscriptionId, f.price, f.size, f.takerSide, f.tradeId);
      break;

The tape needs no state on your side: there is no snapshot (snapshotPending: false on the ack), and frames flow from the moment you subscribe, and earlier fills are not replayed. See the TRADE frame reference for the full semantics. The trade channel is available on Polymarket, Kalshi and ProphetX; Limitless publishes no public trade feed, so a trade subscribe there is rejected with UNSUPPORTED_CHANNEL.

5. Keep the connection healthy

The server sends WebSocket pings every 30 seconds; your client library answers them automatically. You can also send an application-level PING and get a PONG back.
Watch for GOODBYE frames and socket closes, and reconnect. Connections are closed at the connectionTtlSeconds lifetime from WELCOME, so schedule a proactive reconnect before then.
On a STATUS frame with state: "RESYNCING", drop that subscription’s local book and trust the next SNAPSHOT. See reconnect & resync handling.

The WebSocket API reference documents the full wire contract, one page per concern: Authentication, Connection lifecycle, Subscriptions & markets, the Orderbook and Trades channels, Errors & status, and the full Message catalog.

Get started

Connecting

Market data

Reference

Prerequisites

1. Connect and authenticate

2. Receive `WELCOME`

4. Apply the stream

Optional: the trade tape

5. Keep the connection healthy

Next

​Prerequisites

​1. Connect and authenticate

​2. Receive WELCOME

​3. Subscribe

​4. Apply the stream

​Optional: the trade tape

​5. Keep the connection healthy

​Next

Prerequisites

1. Connect and authenticate

2. Receive `WELCOME`

3. Subscribe

4. Apply the stream

Optional: the trade tape

5. Keep the connection healthy

Next