TESTNET
Connect

WebSocket session model

Polyester WebSocket subscriptions deliver live market and account updates without polling. Use them alongside REST or ConnectRPC: unary APIs establish or reconcile state, while WebSocket channels deliver subsequent changes.

Available streams

  • market trades, candles, and order-book changes
  • market overview and other public market data
  • public lifecycle and configuration events

Connection flow

Prepare private authentication

Public clients skip this step. Private clients use a JWT session or Ed25519 API-key identity to obtain a connection token from /v1/rt/token. The token is valid for 5 minutes from issuance. The response includes expires_unix, the authoritative expiration timestamp in Unix seconds.

Open the realtime connection

Connect to the environment API host at:

/connection/websocket

Private clients include the connection token. Open the connection through the selected SDK's realtime client or a custom WebSocket client.

Authorize and subscribe

Before subscribing to a private channel, obtain its channel-bound token from /v1/rt/subscribe. Subscription tokens are valid for 1 minute from issuance and the response includes their expires_unix value. Public subscriptions need no token. Realtime tokens do not replace authentication for unary write methods.

Decode the matching payload

Use the relevant SDK product method or the exact channel name and payload schema for a custom client. Encoding support is channel-specific.

Reconcile after reconnecting

Restore subscriptions, reload the relevant snapshot or history through REST or ConnectRPC, and reconcile local state before applying new updates.

Delivery and recovery

Within an active subscription, realtime delivery is at least once. Reconnects and backend rebalances can cause duplicate messages, while a disconnected client can miss live messages.

Apply state and configuration snapshots idempotently as replacement state. Use revisions when the schema exposes them, and allow repeated invalidations to trigger the same safe refresh. For event streams, deduplicate with stable identifiers and ordering fields from the payload, never with the number or arrival position of a message.

After reconnecting, reload the relevant snapshot or history through REST or ConnectRPC before resuming live application. Unary APIs remain the authority for reconnect recovery.

Choose a payload guide

Encoding support remains channel-specific. Do not assume that every channel has both variants.

Treat WebSocket delivery as the live update path, not the sole durable record for application state.

See the Connectivity matrix for official SDK repositories and the TypeScript streaming guide for an implementation example.

Public IDs Understand what Polyester public IDs identify, why they are opaque, and how their representation differs per interface. Client order IDs and idempotency Use client order IDs to prevent duplicate placement, correlate client intents, and reconcile uncertain outcomes. Order Sizing Choose exact base-quantity or maximum quote-debit sizing and read the authoritative quantity accepted for execution. Fee Assets Choose whether a BUY fee is charged in quote or deducted from received base, and decode fee amounts with the correct scale. Preview Order Check whether an order is currently admissible without creating an order, reserving funds, or presenting an execution quote. Market Order Price Protection Understand market-order slippage overrides, pair defaults, client reference drift, execution boundaries, and stale-quote errors. Self-Trade Prevention Prevent an incoming order from trading against a resting order from the same trading account. Rate limits Weighted quotas, default limits, rejection metadata, and retry behavior.
Previous

Rate limits
Next

Ed25519 API Keys