WebSocket API Overview for Molecule Real-Time Streams

Connect to Molecule WebSocket streams for real-time orders, fills, positions, balances, orderbooks, and trade prints. Connections require Ed25519 signing.

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.