# STXWebSocket

> The WebSocket client: connecting, joining channels and reconnecting.

Source: https://docs.stxapp.io/sdks/python/reference/stx-websocket/

{/* Generated from the Python source by tools/gen_reference.py. Do not edit by hand. */}

Async Phoenix-channels client for the documented STX topics.

Build it from an `AsyncSTX` client, which supplies the host, the key
and your user id:

```python
async with AsyncSTX() as client:
    async with client.websocket() as ws:
        book = await ws.orderbook(["<market-id>"], on_message=print)
        orders = await ws.orders()
        print(await orders.wait_snapshot())
        await ws.run_forever()
```

or standalone with the same settings arguments as `AsyncSTX`.

## Constructor

| Parameter | Description |
|---|---|
| `rest` | an `AsyncSTX` to take host, key and user id from. |
| `user_id` | your user id, if you already have it (skips `GET /me`). |
| `heartbeat_interval` | seconds between socket heartbeats. The server closes a socket silent for 60 s. |
| `channel_ping_interval` | seconds between channel `ping` frames on every joined topic; `None` disables them. `orders` with cancel-on-disconnect pings faster, from the granted timeout. |
| `reconnect` | reconnect after a drop (default `True`). |
| `reconnect_policy` | backoff for reconnects. |
| `on_reconnect` | called (sync or async) after every successful reconnect and rejoin: the moment to call `orders()` and anything else you show again. |
| `join_timeout` | seconds to wait for a join or push reply. |
| `queue_size` | messages buffered per channel for `async for`; the oldest is dropped when full. |

## Attributes

| Attribute | Type | Description |
|---|---|---|
| `url` | `str` |  |
| `verify_tls` | `bool` |  |
| `channels` | `Dict[str, Channel]` |  |
| `connected` | `bool` |  |

## Methods

### `account()`

```python
account(*, market_ids: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`account:{user_id}`: everything the five channels above carry, on
one join. Do not also join a per-type channel (you would get every
message twice), and use `orders` if you need cancel-on-disconnect.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `balances()`

```python
balances(*, account_id: Optional[str] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`balances:{user_id}`: `balances` on join, then `update` and
`payment_update`. `account_id` picks one of your accounts.

| Parameter | Type | Description |
|---|---|---|
| `account_id` | `Optional[str]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `connect()`

```python
connect() -> None
```

Open the socket. Idempotent.

### `fills()`

```python
fills(*, market_ids: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`fills:{user_id}`: `all_trades` on join, then one `trade` per
execution or status change.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `join()`

```python
join(topic: str, payload: Optional[Dict[str, Any]] = None, *, on_message: Optional[MessageHandler] = None, ping_interval: Any = _UNSET) -> Channel
```

Join `topic` with `payload` and wait for the reply.

Raises `STXChannelException` with the server's reason (for example
`market_ids_required` or `unauthorized`) if the join is refused.

| Parameter | Type | Description |
|---|---|---|
| `topic` | `str` |  |
| `payload` | `Optional[Dict[str, Any]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |
| `ping_interval` | `Any` |  |

### `market_stats()`

```python
market_stats(market_ids: Sequence[str], *, range: Optional[str] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`market_stats`: a price series per market. The history is in the
join reply (`channel.reply["markets"]`); `market_stats` pushes
changed buckets (upsert by `timestamp_us`) and
`market_stats_snapshot` replaces a series.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Sequence[str]` |  |
| `range` | `Optional[str]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `market_updates()`

```python
market_updates(watch: Optional[Sequence[str]] = None, *, on_message: Optional[MessageHandler] = None) -> Channel
```

`market_updates`: `created` and `updated` for the markets you
watch. Nothing arrives until you watch something; pass `watch=` or
call `channel.watch([...])`. Prices are converted from cents to
dollar strings here.

| Parameter | Type | Description |
|---|---|---|
| `watch` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `markets()`

```python
markets(*, rule_filters: Optional[Sequence[str]] = None, message_types: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`markets`: `market_created` and `market_updated` for every
market. Each payload maps market id to a market object;
`market_updated` carries only the changed fields. Prices arrive in
cents on the wire and are converted to dollar strings here.

| Parameter | Type | Description |
|---|---|---|
| `rule_filters` | `Optional[Sequence[str]]` |  |
| `message_types` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `orderbook()`

```python
orderbook(market_ids: Sequence[str], *, on_message: Optional[MessageHandler] = None) -> Channel
```

`orderbook`: the aggregated book, one `book` push per market.

Each push is a full snapshot of that market's book; replace what you
hold rather than merging. `market_ids` is required.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Sequence[str]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `orders()`

```python
orders(*, market_ids: Optional[Sequence[str]] = None, cancel_on_disconnect: bool = False, ping_timeout: Optional[int] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`orders:{user_id}`: `all_orders` on join, then `new_open_order`.

`cancel_on_disconnect=True` arms cancel-on-disconnect for orders
placed with `cancel_on_disconnect=True`. `ping_timeout` is in
milliseconds, clamped by the server to 5000 to 20000; the granted
value is in `channel.reply["ping_timeout"]` and the SDK pings at
60% of it for as long as the channel is joined.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Optional[Sequence[str]]` |  |
| `cancel_on_disconnect` | `bool` |  |
| `ping_timeout` | `Optional[int]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `positions()`

```python
positions(*, market_ids: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`positions:{user_id}`: `all_positions` on join, then
`updated_positions` deltas with only the changed positions.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `run_forever()`

```python
run_forever() -> None
```

Block until `close` is called (or reconnects are exhausted).

### `settlements()`

```python
settlements(*, market_ids: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`settlements:{user_id}`: `new_settlements` as they are recorded.
No snapshot; history is `AsyncSTX.settlements()`.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `ticker()`

```python
ticker(*, sports: Optional[Sequence[str]] = None, competitions: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`ticker`: a `ticker` push whenever a market's price, top of
book, volume or open interest moves. No snapshot on join.

| Parameter | Type | Description |
|---|---|---|
| `sports` | `Optional[Sequence[str]]` |  |
| `competitions` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `trades()`

```python
trades(*, market_ids: Optional[Sequence[str]] = None, event_ids: Optional[Sequence[str]] = None, on_message: Optional[MessageHandler] = None) -> Channel
```

`trades`: every execution on the exchange, anonymised. `action`
is the taker's side. Not your fills: see `fills`.

| Parameter | Type | Description |
|---|---|---|
| `market_ids` | `Optional[Sequence[str]]` |  |
| `event_ids` | `Optional[Sequence[str]]` |  |
| `on_message` | `Optional[MessageHandler]` |  |

### `user_id()`

```python
user_id() -> str
```

Your user id, from `user_id=` or `GET /api/v1/me`.

### `user_info()`

```python
user_info(*, on_message: Optional[MessageHandler] = None) -> Channel
```

`user_info:{user_id}`: `user_updated` right after joining, then
on every profile change.

| Parameter | Type | Description |
|---|---|---|
| `on_message` | `Optional[MessageHandler]` |  |