> ## Documentation Index
> Fetch the complete documentation index at: https://molelcule.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```python theme={"dark"}
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"])
```

<Note>
  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.
</Note>

***

## 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`

```python theme={"dark"}
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"])
```

<Note>
  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.
</Note>

***

## 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`

```python theme={"dark"}
url = client.ws.positions({"subaccount_id": subaccount_id})

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

<Note>
  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.
</Note>

***

## 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`

```python theme={"dark"}
url = client.ws.balances({"subaccount_id": subaccount_id})

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

<Note>
  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.
</Note>

***

## 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`

```python theme={"dark"}
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)
```

<Note>
  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.
</Note>

***

## 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}`

```python theme={"dark"}
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)
```

<ParamField path="generic_asset_id" type="integer | string" required>
  The cross-venue asset ID to subscribe to. The SDK embeds this directly in the URL path.
</ParamField>

<Note>
  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.
</Note>

***

## 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`

```python theme={"dark"}
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"])
```

<Note>
  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.
</Note>

***

## 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

```python theme={"dark"}
# 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` |

<Note>
  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.
</Note>

***

## 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

```python theme={"dark"}
# 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)
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.