WebSocket entry point. Thin wrapper around ZenWebsocket.Client that binds
a %CCXT.Exchange{} to a connection so subscribe/3 can pick the correct
exchange-native frame builder.
Layer 1+2 (Task 92)
Pure URL resolution (CCXT.WS.URLRouting) + connection lifecycle (this module).
Layer 3 (auth state machine, custom reconnection) is deliberately deferred —
zen_websocket covers reconnection, backoff, heartbeat, and subscription
restoration natively.
Usage
{:ok, ws} = CCXT.WS.connect(exchange, :public)
:ok = CCXT.WS.subscribe(ws, ["tickers.BTCUSDT"])
# Messages arrive at the calling process as {:websocket_message, decoded_map}
CCXT.WS.close(ws)For deribit's JSON-RPC subscribe (which carries an id field), subscribe/3
returns {:ok, response} from zenwebsocket's request-correlation; for bybit
and okx it returns :ok and the subscribe-ack arrives asynchronously as a
`{:websocket_message, }` message.
Scope
Three canary exchanges are wired today: bybit, deribit, okx. Other
priority-tier exchanges land in T93 (auth) + T94 (subscription patterns).
Summary
Functions
Closes the WebSocket connection.
Connects to the exchange's WebSocket endpoint for the given section
(:public or :private).
Returns the current connection state (:connecting, :connected, or :disconnected).
Returns the resolved WS URL this connection is using.
Sends a raw (already-encoded or map) payload. Delegates to zen_websocket.
Sends an exchange-native subscribe frame for the given channels.
Types
@type section() :: :public | :private
@type t() :: %CCXT.WS{ exchange: CCXT.Exchange.t(), section: section(), url: String.t(), zen_client: ZenWebsocket.Client.t() }
Functions
@spec close(t()) :: :ok
Closes the WebSocket connection.
@spec connect(CCXT.Exchange.t(), section(), keyword()) :: {:ok, t()} | {:error, term()}
Connects to the exchange's WebSocket endpoint for the given section
(:public or :private).
Extra opts are forwarded to ZenWebsocket.Client.connect/2. The connection's
heartbeat config is resolved from CCXT.WS.Config unless the caller overrides
heartbeat_config in opts.
Returns {:error, :unsupported_exchange} if the exchange has no WS config,
or {:error, :no_url_configured} if the requested section is absent.
@spec get_state(t()) :: :connecting | :connected | :disconnected
Returns the current connection state (:connecting, :connected, or :disconnected).
Returns the resolved WS URL this connection is using.
Sends a raw (already-encoded or map) payload. Delegates to zen_websocket.
@spec subscribe(t(), [String.t() | map()], keyword() | map()) :: :ok | {:ok, map()} | {:error, term()}
Sends an exchange-native subscribe frame for the given channels.
The frame is built by the exchange's registered subscription_pattern module
(via CCXT.WS.Subscription.build_subscribe/3), encoded as JSON, and sent via
ZenWebsocket.Client.send_message/2.
Pattern modules return either a single map (most exchanges) or a list of maps
(:sub_subscribe, :reqtype_sub, and :custom with array_format —
HTX/BingX/Upbit emit one frame per channel). List returns are sent
sequentially; the function returns :ok only if every frame sent successfully.
For frames with an id field (deribit JSON-RPC), send_message/2 blocks on
the correlated response and returns {:ok, response}. For frames without an
id (bybit, okx, etc.), returns :ok.
Extra opts merge into the exchange's subscription_config from
CCXT.WS.Config — used for runtime overrides like a fresh JSON-RPC id or an
inline auth token. Keys must be atoms to override the atom-keyed base config;
string-keyed maps coexist rather than override.
TODO(adapter): :rest_token (kraken) and :inline_subscribe (coinbase) auth
patterns require per-frame auth injection via CCXT.WS.Auth.build_subscribe_auth/5,
which this function does not call. Private subscribes on those exchanges ship
unauthenticated until the adapter layer lands (see CHANGELOG T94).