WebSocket API Overview for Molecule Real-Time Streams

The Molecule WebSocket API delivers real-time event streams for orders, fills, positions, balances, order books, and trade prints. Rather than polling REST endpoints, you subscribe to the relevant stream and receive pushed updates as events occur on the platform. All WebSocket connections authenticate via signed query parameters derived from your Ed25519 key — the SDK generates these URLs automatically.

Available endpoints

Stream	Path	Description
Orders	`/v1/ws/orders`	Your order status updates in real time
Fills	`/v1/ws/fills`	Execution fill events
Positions	`/v1/ws/positions`	Position change events
Balances	`/v1/ws/balances`	Balance change events
Orderbooks	`/v1/ws/orderbooks`	Order book snapshots and updates
Tradeprints	`/v1/ws/tradeprints`	Public trade print events

Authentication

WebSocket connections authenticate via signed query parameters rather than HTTP headers. The query string includes three parameters:

Parameter	Description
`key_id`	Your API key ID
`ts`	Unix timestamp of the request (must be within the 30-second replay window)
`sig`	Ed25519 signature over the path and timestamp

The SDK’s client.ws.*() methods generate correctly signed URLs automatically. Pass any additional filter parameters (such as subaccount_id or instrument_id) as a dict — they are merged into the signed query string.

from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.trade",
    key_id="key_abc123",
    private_key="<base64-encoded-ed25519-seed>",
)

subaccount_id = "sa_abc123"

# Returns a signed wss:// URL ready to connect
url = client.ws.orders({"subaccount_id": subaccount_id})
# e.g. wss://api.molecule.trade/v1/ws/orders?subaccount_id=sa_abc123&key_id=key_abc123&ts=1710000000&sig=<sig>

Signed URLs expire after 30 seconds. Generate a fresh URL for each new connection; do not cache and reuse a previously signed URL.

Consuming messages

The SDK provides two patterns for consuming WebSocket streams:

Pattern 1: `client.iter_ws` — blocking iterator

client.iter_ws(path, params) connects to the signed URL, then yields parsed JSON objects for each message received. This is the simplest pattern for synchronous consumers.

from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.trade",
    key_id="key_abc123",
    private_key="<base64-encoded-ed25519-seed>",
)

# Stream order updates for a subaccount
for message in client.iter_ws("/v1/ws/orders", {"subaccount_id": "sa_abc123"}):
    print(message)

client.iter_ws requires the websockets package. Install it with pip install websockets if it is not already present in your environment. The iterator blocks until the connection closes or raises an exception.

Pattern 2: `client.ws.url` — signed URL for any WebSocket library

client.ws.url(path, params) returns a signed wss:// URL you can pass to any WebSocket library — useful when integrating with async frameworks or custom reconnection logic.

import websockets  # or any other WebSocket library

url = client.ws.url("/v1/ws/fills", {"subaccount_id": "sa_abc123"})

# Use with websockets (async example)
async with websockets.connect(url) as ws:
    async for message in ws:
        print(message)

client.iter_ws

Blocking generator. Simplest way to consume a single stream synchronously. Connect, iterate, done.

client.ws.url

Returns a signed URL. Use with any WebSocket library, async framework, or custom reconnect wrapper.

Path aliases

When calling client.ws.url() or client.iter_ws(), you can pass either the full path or a short alias:

Alias	Resolves to
`"orders"`	`/v1/ws/orders`
`"fills"`	`/v1/ws/fills`
`"positions"`	`/v1/ws/positions`
`"balances"`	`/v1/ws/balances`
`"orderbooks"`	`/v1/ws/orderbooks`
`"tradeprints"`	`/v1/ws/tradeprints`

# These are equivalent
for msg in client.iter_ws("orders", {"subaccount_id": "sa_abc123"}):
    print(msg)

for msg in client.iter_ws("/v1/ws/orders", {"subaccount_id": "sa_abc123"}):
    print(msg)

See the Streams reference for per-stream URL builder methods and their parameters.

Python SDK

Markets

Orders

Portfolio

WebSockets

WebSocket API Overview for Molecule Real-Time Streams

Available endpoints

Authentication

Consuming messages

Pattern 1: `client.iter_ws` — blocking iterator

Pattern 2: `client.ws.url` — signed URL for any WebSocket library

client.iter_ws

client.ws.url

Path aliases

​Available endpoints

​Authentication

​Consuming messages

​Pattern 1: client.iter_ws — blocking iterator

​Pattern 2: client.ws.url — signed URL for any WebSocket library

client.iter_ws

client.ws.url

​Path aliases

Available endpoints

Authentication

Consuming messages

Pattern 1: `client.iter_ws` — blocking iterator

Pattern 2: `client.ws.url` — signed URL for any WebSocket library

Path aliases