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

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

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

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

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

***

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

```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>",
)

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

<Info>
  `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.
</Info>

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

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

<CardGroup cols={2}>
  <Card title="client.iter_ws" icon="rotate">
    Blocking generator. Simplest way to consume a single stream synchronously. Connect, iterate, done.
  </Card>

  <Card title="client.ws.url" icon="link">
    Returns a signed URL. Use with any WebSocket library, async framework, or custom reconnect wrapper.
  </Card>
</CardGroup>

***

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

```python theme={"dark"}
# 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](/api/websockets/streams) for per-stream URL builder methods and their parameters.


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