Authentication

The orderbook stream lives at a single endpoint:

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

Authentication happens during the WebSocket upgrade — there is no separate login message and no token to refresh mid-stream. You either open the connection authenticated, or the upgrade is rejected before the socket opens.

One key for REST and the stream

The stream authenticates with the same signed API key you use for the REST API — an Ed25519 keypair whose public half is registered to your actor. There is no separate stream credential. You sign the handshake with your private key exactly the way you sign a REST request; the private key never leaves your side.

Signing the handshake

Because a browser cannot set custom headers on a WebSocket upgrade, the signed credentials ride the query string:

Parameter	Value
`keyId`	Your API key id (the same one you send as `PX-Key-Id` on REST).
`timestamp`	Unix seconds, within ±30s of the server clock.
`signature`	Ed25519 signature (lowercase hex) over the canonical string below.

The canonical string is the REST canonical with the method literal WS, the sorted query excluding keyId/timestamp/signature, and the empty-body hash:

WS
/v1/orderbook
<sorted query without the credential params>
<timestamp>
<sha256 of the empty string, lowercase hex>

Signing it with the WS method means a handshake signature can never be replayed against a REST request on the same path, and vice versa. Signing it is a few lines with the standard library — the same Ed25519 signature you produce for REST, over this canonical 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();

/* Your Ed25519 signing key, from its 32-byte seed (hex). The private key never
   leaves your machine. */
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}`,
);

(The empty middle line is the sorted query with the credential params removed — empty here because the orderbook endpoint takes no other query parameters.)

Keep your timestamp in unix seconds and synced to the server clock (see GET /v1/time); a signature outside the ±30s window is rejected. A signature authorizes only this exact handshake and expires with its timestamp window, so a leaked URL stops working within seconds rather than being a durable credential — but the private key that produced it is the real secret: guard it, and never put it in a URL.

Handshake responses

The outcome of authentication is an HTTP status on the upgrade request, before any frame is sent:

Status	Meaning	What to do
`101`	Switching Protocols — the connection is open.	Wait for the `welcome` frame.
`401`	The credentials are missing, or the signature/timestamp is invalid.	Re-sign with a fresh timestamp; check the key id and clock sync. Don’t retry an identical rejected handshake.
`429`	Your account is at its `maxConnections` limit.	Close a connection you no longer need; retrying alone won’t help.
`503`	The gateway is at capacity, or a transient key-lookup fault.	Back off briefly and retry — the same signed handshake is valid within its window.

Once the upgrade succeeds the server immediately sends a welcome frame. From there, see Subscriptions & markets to start streaming.

Get started

Connecting

Market data

Reference

One key for REST and the stream

Signing the handshake

Handshake responses

​One key for REST and the stream

​Signing the handshake

​Handshake responses

One key for REST and the stream

Signing the handshake

Handshake responses