Compression

High-throughput sockets can opt into zstd compression. It’s negotiated once at the WebSocket upgrade and is connection-scoped: it applies to every room subscription on that connection, and can’t be changed without reconnecting. When enabled, room envelopes arrive as binary frames of zstd-compressed JSON rather than text frames. Everything else about the protocol is unchanged, only the wire format of inbound messages differs.

Enabling compression

Request compression at the handshake in one of two ways:

Method	How	When to use
Header	`X-Ws-Compression: zstd`	Preferred. Any client that can set upgrade headers.
Query	`?compression=zstd`	Fallback for browsers, which can’t set headers on the `WebSocket` constructor.

wss://api.struct.to/ws?api-key=YOUR_API_KEY&compression=zstd

Omit both the header and the query parameter for the default uncompressed text frames. zstd is the only supported value; an unsupported value fails the upgrade with 400. Subscribe-message compression is not used, only the handshake matters.

The header is preferred because it keeps the compression choice out of the URL and logs. Use the query parameter only when your client can’t set upgrade headers, as is the case for the browser WebSocket constructor. If you set both, they must agree.

Decoding frames

A compressed connection delivers each room envelope as a binary frame. Decompress the bytes with zstd, then JSON.parse the resulting UTF-8 string exactly as you would an uncompressed text frame.

import WebSocket from "ws";
import { decompress } from "fzstd";

const ws = new WebSocket("wss://api.struct.to/ws?api-key=YOUR_API_KEY", {
  headers: { "X-Ws-Compression": "zstd" },
});

const decoder = new TextDecoder();
ws.on("message", (data: Buffer, isBinary: boolean) => {
  const raw = isBinary ? decoder.decode(decompress(new Uint8Array(data))) : data.toString();
  const msg = JSON.parse(raw);
  console.log(msg.type, msg.message);
});

import { decompress } from "fzstd";

const ws = new WebSocket("wss://api.struct.to/ws?api-key=YOUR_API_KEY&compression=zstd");
ws.binaryType = "arraybuffer";

const decoder = new TextDecoder();
ws.onmessage = (event) => {
  const raw =
    event.data instanceof ArrayBuffer
      ? decoder.decode(decompress(new Uint8Array(event.data)))
      : event.data;
  const msg = JSON.parse(raw);
  console.log(msg.type, msg.message);
};

import asyncio
import json
import zstandard
import websockets

async def main():
    uri = "wss://api.struct.to/ws?api-key=YOUR_API_KEY"
    dctx = zstandard.ZstdDecompressor()
    async with websockets.connect(uri, additional_headers={"X-Ws-Compression": "zstd"}) as ws:
        async for frame in ws:
            raw = dctx.decompress(frame) if isinstance(frame, bytes) else frame
            msg = json.loads(raw)
            print(msg["type"], msg.get("message"))

asyncio.run(main())

Browsers have no native zstd decoder (DecompressionStream supports only gzip and deflate), so a browser client needs a small library such as fzstd to decompress frames. The TypeScript SDK handles this for you.

Branch on the frame type rather than assuming every frame is binary. Text control frames such as the {"type":"pong"} keepalive reply still arrive as text, so a typeof data === "string" (or isBinary / instanceof ArrayBuffer) check keeps both paths working on the same connection.

Confirming the negotiated mode

Each room’s *_subscribe_response echoes a compression field reporting whether zstd delivery is active for the connection, so you can assert the negotiation succeeded without inspecting frame types.

{
  "type": "trade_stream_subscribe_response",
  "message": { "compression": "zstd", "subscribe_all": false }
}

When to use it

Compression trades a little CPU on both ends for lower bandwidth. It pays off most on high-volume subscriptions, verbose JSON payloads (metrics and order-book rooms), firehose subscriptions, and bandwidth-constrained or metered clients. For a handful of narrowly filtered rooms the savings are marginal, so leave it off unless you’re moving real volume.

The dashboard websockets playground has a zstd compression toggle on the connection card, so you can watch compressed delivery end to end before wiring it into your own client.

Next steps

Firehose subscriptions — the highest-volume streams, where compression matters most.
WebSocket Pricing — per-message rates (compression doesn’t change billing; you’re billed per message, not per byte).
Getting Started — the full Rooms protocol.

Introduction

Rooms

Alerts

Enabling compression

Decoding frames

Confirming the negotiated mode

When to use it

Next steps

​Enabling compression

​Decoding frames

​Confirming the negotiated mode

​When to use it

​Next steps

Enabling compression

Decoding frames

Confirming the negotiated mode

When to use it

Next steps