Molecule WebSocket Streams — URL Builder Reference

URL builder methods for all Molecule WebSocket streams: ws.orders, ws.fills, ws.positions, ws.balances, ws.orderbooks, ws.tradeprints, and generic asset.

Each method on client.ws builds a signed wss:// URL for a specific stream. Pass an optional params dict of filter parameters — such as subaccount_id or instrument_id — to scope the stream to your use case. The returned URL includes key_id, ts, and sig query parameters derived from your Ed25519 key and is valid for 30 seconds from the moment it is generated.

---

ws.orders

Build a signed URL for the /v1/ws/orders stream, which delivers real-time order status transitions for your subaccount.

Method: client.ws.orders(params=None) → signed URL for /v1/ws/orders

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"

url = client.ws.orders({"subaccount_id": subaccount_id})
# wss://api.molecule.trade/v1/ws/orders?subaccount_id=sa_abc123&key_id=...&ts=...&sig=...

for message in client.iter_ws("/v1/ws/orders", {"subaccount_id": subaccount_id}):
    print(message["id"], message["status"])

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.fills

Build a signed URL for the /v1/ws/fills stream, which delivers fill events as your orders execute.

Method: client.ws.fills(params=None) → signed URL for /v1/ws/fills

url = client.ws.fills({"subaccount_id": subaccount_id})

for fill in client.iter_ws("/v1/ws/fills", {"subaccount_id": subaccount_id}):
    print(fill["order_id"], fill["price"], fill["qty"])

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.positions

Build a signed URL for the /v1/ws/positions stream, which delivers position change events as your holdings update.

Method: client.ws.positions(params=None) → signed URL for /v1/ws/positions

url = client.ws.positions({"subaccount_id": subaccount_id})

for event in client.iter_ws("/v1/ws/positions", {"subaccount_id": subaccount_id}):
    print(event)

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.balances

Build a signed URL for the /v1/ws/balances stream, which delivers balance change events as funds move or orders settle.

Method: client.ws.balances(params=None) → signed URL for /v1/ws/balances

url = client.ws.balances({"subaccount_id": subaccount_id})

for event in client.iter_ws("/v1/ws/balances", {"subaccount_id": subaccount_id}):
    print(event)

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.orderbooks

Build a signed URL for the /v1/ws/orderbooks stream, which delivers order book snapshots and incremental updates for a specific instrument.

Method: client.ws.orderbooks(params=None) → signed URL for /v1/ws/orderbooks

instrument_id = 42

url = client.ws.orderbooks({"instrument_id": instrument_id})

for snapshot in client.iter_ws("/v1/ws/orderbooks", {"instrument_id": instrument_id}):
    print(snapshot)

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.generic_asset_orderbook

Build a signed URL for the /v1/ws/orderbooks/generic-asset/{id} stream, which aggregates order book data across venues for a cross-venue asset.

Method: client.ws.generic_asset_orderbook(generic_asset_id, params=None) → signed URL for /v1/ws/orderbooks/generic-asset/{id}

url = client.ws.generic_asset_orderbook(100, {"subaccount_id": subaccount_id})

for snapshot in client.iter_ws(
    "/v1/ws/orderbooks/generic-asset/100",
    {"subaccount_id": subaccount_id},
):
    print(snapshot)

generic_asset_id · integer | string · required

The cross-venue asset ID to subscribe to. The SDK embeds this directly in the URL path.

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.tradeprints

Build a signed URL for the /v1/ws/tradeprints stream, which delivers public trade print events (last-sale records) as trades occur on the book.

Method: client.ws.tradeprints(params=None) → signed URL for /v1/ws/tradeprints

url = client.ws.tradeprints({"instrument_id": instrument_id})

for print_event in client.iter_ws("/v1/ws/tradeprints", {"instrument_id": instrument_id}):
    print(print_event["price"], print_event["qty"], print_event["created_at"])

The returned URL includes key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.url

General-purpose signed URL builder. Accepts a full path or a short alias (see table below) and an optional params dict. Use this method when building integrations that reference stream names dynamically or when you need to pass a URL to a third-party WebSocket library.

Method: client.ws.url(path, params=None) — general signed URL builder

# Using a full path
url = client.ws.url("/v1/ws/orders", {"subaccount_id": subaccount_id})

# Using a short alias — resolves to /v1/ws/orders automatically
url = client.ws.url("orders", {"subaccount_id": subaccount_id})

# Using a generic-asset orderbook path
url = client.ws.url("/v1/ws/orderbooks/generic-asset/100", {"subaccount_id": subaccount_id})

Supported short aliases:

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

All URLs built by ws.url() include key_id, ts, and sig query parameters from the Ed25519 signer. Regenerate the URL for each new connection — signed URLs expire after 30 seconds.

---

ws.iter

Delegate to client.iter_ws() via the client.ws namespace. Connects to the signed URL for path and yields parsed JSON objects for each message.

Method: client.ws.iter(path, params=None) — delegates to client.iter_ws(); yields parsed JSON

# Equivalent to client.iter_ws("/v1/ws/orders", {...})
for message in client.ws.iter("/v1/ws/orders", {"subaccount_id": subaccount_id}):
    print(message)

# Short alias also works
for message in client.ws.iter("orders", {"subaccount_id": subaccount_id}):
    print(message)

ws.iter() and client.iter_ws() both require the websockets package. Install it with pip install websockets. The iterator blocks until the connection closes.