Getting started

SBE WebSocket is the specialized path for clients that prioritize minimal encoding and transport overhead for order entry. It uses Simple Binary Encoding in binary WebSocket frames.

Command path, not state stream

Use SBE WebSocket for order commands and immediate acknowledgements. Use WebSocket Protobuf for typed market, execution, and account events, and use REST or ConnectRPC for state reconciliation. This interface is separate from FIX-SBE and Polyester's internal SBE transports.

When to use SBE WebSocket

Use this interface for latency-sensitive trading systems that:

maintain long-lived authenticated sessions
encode and decode fixed-layout binary messages
manage strict client sequencing and backpressure
operate REST, ConnectRPC, or realtime subscriptions alongside order entry

Use an official SDK with ConnectRPC when typed API access and broader service coverage matter more than the smallest order-entry wire format.

Session flow

Sign the WebSocket upgrade

Connect to the environment API host at:

/ws/trade.sbe

Authenticate the WebSocket upgrade with the Ed25519 API-key headers described in Ed25519 API keys. The session is bound to the key's root-account or subaccount scope.

Start the connection sequence

Begin at sequence 1. Every subsequent command on the same connection must use the next contiguous sequence number and a client correlation value.

Send an SBE command

Encode one supported command with the published SBE schema and send it in a binary WebSocket frame.

Handle the response

Match the echoed sequence and correlation values to the command. Handle the command acknowledgement, command rejection, or pong response.

Reconcile application state

After reconnecting or receiving an uncertain command outcome, use REST or ConnectRPC to reload state before resuming decisions.

Message scope

create order
cancel order
modify order
cancel all orders
ping

Create-order sizing in schema version 2

Every CreateOrder command must set sizingKind and exactly one matching quantity field:

`sizingKind`	Required value field	Field that must use its null value
`BASE_QUANTITY`	`baseQtyScaled`	`maxQuoteDebitScaled`
`MAX_QUOTE_DEBIT`	`maxQuoteDebitScaled`	`baseQtyScaled`

MAX_QUOTE_DEBIT is valid only for BUY Market IOC and BUY Limit IOC. It is a hard all-in quote ceiling. BASE_QUANTITY is an exact gross base quantity.

Set feeAsset to QUOTE or BASE. BASE is valid only for BUY. A successful create acknowledgement returns resolvedBaseQtyScaled and returns submittedMaxQuoteDebitScaled when a quote budget was submitted.

Populating baseQtyScaled alone is not enough

Schema version 2 requires sizingKind. A zero-initialized or omitted sizing enum is rejected even when baseQtyScaled contains a positive value.

The SBE command path does not expose order preview. Use Preview Order over REST or ConnectRPC when an integration needs a non-mutating account admission check. See Order Sizing for schema-version-2 quantity fields and acknowledgement semantics.

See the Connectivity matrix for the role of each interface.