polyester-sdk 0.1.0a55__tar.gz → 0.2.0__tar.gz

{polyester_sdk-0.1.0a55 → polyester_sdk-0.2.0}/.env.example

@@ -36,8 +36,8 @@ POLYESTER_ACCOUNT_ID=your_account_id_here
 # POLYESTER_ENV=devnet
 
 # Optional URL overrides (defaults come from the selected environment)
-# POLYESTER_API_URL=https://api-devnet.polyester.ai
-# POLYESTER_WS_URL=wss://api-devnet.polyester.ai
+# POLYESTER_API_URL=https://api.devnet.polyester.com
+# POLYESTER_WS_URL=wss://api.devnet.polyester.com
 
 # On-chain Funding UserOps — caller-supplied EOA, NOT the API ed25519 key
 # and NOT a UI-exported "owner private key". SDK derives the Polyester Safe from this.

{polyester_sdk-0.1.0a55 → polyester_sdk-0.2.0}/CHANGELOG.md

@@ -1,6 +1,157 @@
 # Changelog
 
-## Unreleased
+## 0.2.0
+
+Git tag: `v0.2.0`.
+
+**Upgrade before trading.** 0.1.0a55 and earlier encode and decode prices at
+6 decimals while the API uses 9, so every price is 1,000 times off. Their
+testnet preset points at a host that does not exist, and their devnet preset
+at an undocumented host. This release uses 9-decimal prices and the
+documented hosts (`api.devnet.polyester.com`, `api.testnet.polyester.com`),
+and streams live orders over the private WebSocket.
+
+**New version scheme.** The Go, Python and Rust SDKs now share one version
+line and release together. Versions are plain SemVer (`0.2.0`, `0.2.1`,
+`0.3.0`) instead of PEP 440 pre-releases (`0.1.0aN`), and Git tags are
+`vX.Y.Z`. Before 1.0, a minor release (`0.3.0`) may include breaking changes;
+a patch release (`0.2.1`) does not. Pin the exact version
+(`polyester-sdk==0.2.0`). This release covers every change since 0.1.0a55.
+
+### Breaking
+- Trading prices now use fixed 9-decimal price ticks (one tick is 1e-9 quote
+  units), matching the API. This covers order, trigger, trailing-stop,
+  ladder, order-book, trade, candle, and market-overview prices and
+  `Price.from_ticks`. Earlier SDK versions encode and decode prices at 6
+  decimals, which is 1,000 times off against the current API; upgrade
+  before trading. Integer `max_slippage_ticks` values are 64-bit Q9 ticks.
+- `orders.subscribe()` now streams live orders over the private WebSocket
+  (`/v1/ws/private`) instead of the retired `private:spot:orders:<account>:proto`
+  realtime channel, which no longer issues subscribe tokens. It yields
+  `PrivateOrdersEvent` values instead of bare `Order` objects:
+  `PrivateOrdersSnapshot` (the full live view), `PrivateOrdersUnit` (changed
+  orders, removed order IDs and order events), `PrivateOrdersReady` (the
+  stream reflects every order read made before the subscribe; wait for it
+  before relying on the stream), `PrivateOrdersStale`,
+  `PrivateOrdersConnected`, `PrivateOrdersDisconnected` and
+  `PrivateOrdersError`. Orders are the same `Order` model the reads return.
+  The stream resumes from its last position after a gap, an expired token or
+  a reconnect. `orders.subscribe_sync(on_event=...)` receives the same events.
+- `market_data.get_trades()` drops `from_match_id`, which never reached the
+  API (it failed before sending), and `MarketTradesResult.next_match_id` is
+  now `next_page_token`. Page a listing with `page_token`.
+- A stop-loss or take-profit with a limit child now rejects
+  `max_slippage_ticks` / `max_slippage_bps`, and a sell trailing stop rejects
+  `limit_price`; earlier versions ignored them.
+- `triggers.create()` no longer defaults `trigger_price_source` to `"last"`;
+  unset means the last trade price. A TWAP or ladder trigger now rejects
+  `trigger_price_source`, which earlier versions ignored.
+
+### Changed
+- Documentation links (the PyPI "Documentation" URL, the README capability
+  matrix and Market Order Price Protection links) now point at the public
+  docs on `https://polyester.com/docs`. The price-protection link was
+  broken in earlier versions.
+- Candle and market-overview base volume now use the base asset
+  `market_data_volume_scale` from `get_spot_config`. Primary candle prices
+  use the 9-decimal price scale.
+- Composite reference-candle OHLC uses the pair `reference_price_scale`.
+  `get_candles(..., include_reference=True)` requests that series.
+  `MarketOverviewEntry.volume_24h_base` is the decoded decimal when the
+  catalog scale is known; `volume_24h_base_scaled` stays the integer.
+
+### Added
+- Index-price triggers: stop-loss, take-profit and trailing-stop triggers,
+  standalone (`triggers.create(trigger_price_source=...)`) or attached to an
+  order (`trigger_price_source` on each attached leg, in create and modify),
+  accept `"last"`, `"index"` or `"mark"`; unset means the last trade price.
+  Reads report the same label on `Trigger.trigger_price_source`,
+  `RiskLeg.trigger_price_source` and `TrailingStop.trigger_price_source`, so
+  a leg read from an order can be passed back unchanged. Earlier versions
+  rejected the field on attached legs and dropped it on standalone triggers.
+- `CancelAllOrdersResult.listing_status`: `included`, or
+  `not_retained_read_open_orders` for a retry with the same `request_id`
+  within 120 seconds. Such a retry returns the original counts with an empty
+  `cancelled_orders`; the empty list does not mean nothing was cancelled.
+- `CancelAllAfterResult.effective_scope` (`DeadManSwitchScope` with
+  `account_id`, `symbol_id` and `side`): the orders an armed switch cancels
+  on expiry. `None` when the switch is disabled.
+- `GetOrderResult.executions_complete`: true when the order's trades across
+  every page add up to its filled quantity.
+- `LifecycleFlowSummary.is_delayed`: true when an open flow has made no
+  progress for well beyond its expected step time.
+- New named values: lifecycle reason `deposit_source_not_confirmed`; trigger
+  cancel reasons `account_repair`, `pair_drain_trigger`, `pair_drain_twap`,
+  `pair_drain_ladder` and `pair_drain_attached_leg`; trigger failure reasons
+  `index_price_unavailable` and `trigger_would_trigger_immediately`; order
+  error code `ERROR_CODE_TRIGGER_WOULD_TRIGGER_IMMEDIATELY`; pair status
+  `PAIR_STATUS_HALTED` (only cancellations are accepted).
+- Standalone buy trailing stops: `triggers.create(trigger_type="trailing_stop",
+  side="buy", limit_price=...)`, where `limit_price` is the required maximum
+  price (decimal or `Price.from_ticks`). Trigger reads show a buy trailing
+  stop as an IOC limit child with its maximum price as `limit_price`, and
+  `details.trailing.trough_price` as the lowest price tracked.
+- `CancelAllOrdersResult.cancelled_orders` (up to 200 `CancelledOrder`
+  entries with `order_id` and `client_order_id`, oldest first),
+  `total_cancelled` and `truncated`.
+- Gap-free public trade backfill: `market_data.get_trades(after_trade_id=...)`
+  walks a market's trades by trade ID, oldest first. Results carry
+  `complete_through_trade_id`, `next_after_trade_id` and `epoch_ends`
+  (`TradeEpochEnd`). `get_trades()` also accepts `start_time`, `end_time`,
+  `side` and `page_token`.
+- `OrderMutationResult` (from `orders.create`), `ModifyOrderResult` and
+  accepted `BatchCreateResultItem` entries carry `take_profit_trigger_id`,
+  `stop_loss_trigger_id` and `trailing_stop_trigger_id`: the public IDs of
+  the triggers created for the order's attached-risk legs. Each is set only
+  for a leg the order configured and is empty otherwise.
+- `PolyesterRealtimeError.code` (private WebSocket request error code, for
+  example `FORBIDDEN`) and `PolyesterRealtimeError.close_code` (the WebSocket
+  close code that ended a stream).
+- Trigger events label standalone trailing-stop activation as `activated`,
+  and `trigger_event_type_from_label` accepts `activated` as a filter.
+
+### Fixed
+- `mutation_outcome_unknown()` now returns true for an order or trigger
+  create, cancel, modify or control that was sent but not confirmed in time:
+  every orders error code ending in `_OUTCOME_UNKNOWN`
+  (`ERROR_CODE_ORDER_CREATE_OUTCOME_UNKNOWN`,
+  `ERROR_CODE_ORDER_CANCEL_OUTCOME_UNKNOWN`,
+  `ERROR_CODE_ORDER_MODIFY_OUTCOME_UNKNOWN`,
+  `ERROR_CODE_TRIGGER_CREATE_OUTCOME_UNKNOWN`,
+  `ERROR_CODE_TRIGGER_CONTROL_OUTCOME_UNKNOWN`, and codes added later).
+  `is_retryable_error()` returns false for them: the change may have been
+  applied, so a retry loop that resends it could, for example, place an
+  order twice. Read the order or trigger back before sending it again.
+  Earlier versions treated these as definite failures.
+- `is_retryable_error()` returns true for `AUTH_TEMPORARILY_UNAVAILABLE`
+  (exported as a constant): the request changed nothing, so retry it as is.
+- `POLYESTER_TESTNET_ENVIRONMENT` and `environment_from_name("testnet")` now
+  use `https://api.testnet.polyester.com` and `wss://api.testnet.polyester.com`.
+  Earlier versions pointed at `api-testnet.polyester.com`, which does not
+  exist, so every testnet call failed with a DNS error. The devnet preset and
+  the client defaults now use the documented `api.devnet.polyester.com` host.
+- A stop-loss or take-profit market child now carries its
+  `max_slippage_ticks` or `max_slippage_bps` cap. Earlier versions dropped
+  the cap silently, so the pair's default market slippage applied instead.
+- Trigger reads (`triggers.get`, `triggers.list` and the trigger stream)
+  show a stop-loss or take-profit market child's cap as
+  `Trigger.max_slippage` (ticks, as a price delta) or
+  `Trigger.max_slippage_bps`; earlier versions decoded every market child
+  the same way, cap or not.
+- Integer tick counts (`max_slippage_ticks`, `trailing_distance_ticks`,
+  attached-risk `*_ticks` fields) above the 64-bit range raise
+  `PolyesterValidationError` before sending instead of a raw `ValueError`.
+- Order reads no longer report an attached-risk leg whose state is
+  `not_configured`; the server sends that state for a leg the order does
+  not have.
+- An error code this SDK version does not know yet no longer crashes error
+  handling with `ValueError`. Orders, auth, withdraw and transfer errors
+  raise the usual `PolyesterApiError` with `code` set to
+  `UNKNOWN_ERROR_CODE(<number>)`; an orders error that carries rate-limit
+  details is still a `PolyesterRateLimitError`.
+- With `wire_format="json"`, responses that contain fields or enum names
+  this SDK version does not know yet decode instead of failing. Unknown enum
+  names read as the unspecified value.
 
 ## 0.1.0a55
 

{polyester_sdk-0.1.0a55 → polyester_sdk-0.2.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: polyester-sdk
-Version: 0.1.0a55
+Version: 0.2.0
 Summary: Official Python SDK for Polyester APIs.
 Project-URL: Homepage, https://github.com/Fabric-Labs/polyester-sdk-python
-Project-URL: Documentation, https://polyester.ai/docs/sdk/python/get-started/overview
+Project-URL: Documentation, https://polyester.com/docs/sdk/python/get-started/overview
 Project-URL: Repository, https://github.com/Fabric-Labs/polyester-sdk-python
 Project-URL: Issues, https://github.com/Fabric-Labs/polyester-sdk-python/issues
 Author: Fabric Blockchain Labs Inc.
@@ -48,7 +48,8 @@ Description-Content-Type: text/markdown
 Official Python SDK for Polyester APIs, built for trading bots, backend jobs,
 research notebooks, and automation.
 
-**Status:** Alpha (`0.1.0a55`). Proprietary license (not open source).
+**Status:** `0.2.0`, pre-1.0: a minor release may include breaking changes (see
+[CHANGELOG.md](CHANGELOG.md)). Proprietary license (not open source).
 API-key only; no browser login or JWT flows.
 
 Requires **Python 3.11+**.
@@ -98,7 +99,7 @@ Rows marked **No** are intentional for API-key SDKs (use the TypeScript
 browser client for wallet login and session MFA).
 
 Full cross-language comparison:
-[SDK capability matrix](https://polyester.ai/docs/developer-docs/getting-started/sdk-capability-matrix).
+[SDK capability matrix](https://polyester.com/docs/developer-docs/getting-started/sdk-capability-matrix).
 <!-- sdk-capabilities:end -->
 
 Rows marked **Yes** mean that an SDK wrapper exists; deployment authorization
@@ -114,7 +115,7 @@ API-key policy before retrying.
 PyPI: https://pypi.org/project/polyester-sdk/
 
 ```bash
-pip install "polyester-sdk==0.1.0a55"
+pip install "polyester-sdk==0.2.0"
 ```
 
 Realtime (Centrifugo) and on-chain Funding helpers are included by default.
@@ -184,7 +185,7 @@ asyncio.run(main())
 
 Pass an `environment` preset so API, websocket, RPC, and contract pins stay
 together. `POLYESTER_DEVNET_ENVIRONMENT` is the constructor default.
-`POLYESTER_TESTNET_ENVIRONMENT` targets public testnet (`api-testnet.polyester.com`,
+`POLYESTER_TESTNET_ENVIRONMENT` targets public testnet (`api.testnet.polyester.com`,
 chain `888169`). Custom / VPC endpoints use `create_polyester_environment` or
 `environment.with_urls(...)`. `api_url` / `ws_url` remain as transport overrides.
 
@@ -303,7 +304,7 @@ response as an admission acknowledgement and reconcile with `list_open` before
 releasing local state.
 
 Attached take-profit / stop-loss use the same friendly keys as the read
-model (`trigger_price`, `order_type`, `limit_price`). Child execution is
+model (`trigger_price`, `trigger_price_source`, `order_type`, `limit_price`). Child execution is
 `market` (default) or `limit`, not `limit_ioc` / `limit_fok`, and not a
 nested `child.execution` wrapper.
 
@@ -360,7 +361,7 @@ host, so handle an unimplemented/not-found response and do not make Preview a
 prerequisite for order submission.
 
 Market orders are IOC and enforce a slippage-derived execution boundary. See
-[Market Order Price Protection](https://polyester.ai/developer-docs/shared-concepts/market-order-price-protection)
+[Market Order Price Protection](https://polyester.com/docs/developer-docs/shared-concepts/market-order-price-protection)
 before overriding pair defaults. Set at most one of `max_slippage_bps`
 (1–10000) or `max_slippage_ticks`. Omit both to keep the pair default. The
 fields are rejected on limit orders and if both are supplied.
@@ -382,7 +383,7 @@ fails closed on encoding unless the request's `amount_scale` /
 
 Use **decimal strings** or `Decimal` for human-facing `qty` / `price` inputs.
 Do **not** pass floats. `ticks` on `Price` means Polyester protocol price units
-(fixed 1e6), not market tick-size alignment (server validates tick size).
+(fixed 1e9), not market tick-size alignment (server validates tick size).
 Catalog hydration resolves `symbol` → `symbol_id` and quantity scales for
 encoding; pair admission (tick/step/min qty/notional) stays on the API.
 `orders.preview_order(...)` remains the authority for balances, reservations,
@@ -401,7 +402,7 @@ result = await client.orders.create(
     order_type="limit",
     tif="gtc",
     qty=Quantity.from_scaled(1_000_000, scale=8),  # already wire units
-    price=Price.from_ticks(100_000_000),            # 100.000000 at 1e6
+    price=Price.from_ticks(100_000_000_000),        # 100.000000000 at 1e9
     post_only=True,
 )
 # Reads expose the same types: order.price.ticks, order.orig_qty.scaled
@@ -418,6 +419,15 @@ and per-item phases by polling `get_batch_replace_status`. Use
 to `working`, `rejected`, or `terminal`, not as a finality signal. Retry an
 ambiguous batch request with the same `request_id`.
 
+`cancel_all(...)` requests cancellation of every matching order. The result
+lists up to 200 of them, oldest first, in `cancelled_orders` (each with
+`order_id` and `client_order_id`); `total_cancelled` counts all of them and
+`truncated` is true when the list is shorter. Each order's final state comes
+from the order stream and reads. A dry run lists none. Retrying with the same
+`request_id` within 120 seconds returns the original counts with an empty
+`cancelled_orders` and `listing_status="not_retained_read_open_orders"`; the
+empty list does not mean nothing was cancelled, so read open orders instead.
+
 
 Your API key needs a policy that allows trading. Spot orders spend **trading**
 balance (see below).
@@ -515,6 +525,66 @@ armed/terminal timestamps, `trigger_id`, and `child_order_id`; absent policy
 fields remain unset. `Order` also exposes `post_only`. Create/modify accept the
 same policy shape as a dict or `AttachedRisk`.
 
+A stop-loss or take-profit with `order_type="market"` takes an optional
+slippage cap, `max_slippage_ticks` (Q9 ticks) or `max_slippage_bps`, at most
+one; without one the pair's default market slippage applies. A limit child
+takes no cap (its limit price bounds it). Either side may use either child.
+Trigger reads show the cap as `max_slippage` (ticks, as a price delta) or
+`max_slippage_bps`; both unset means the pair default.
+
+```python
+await client.triggers.create(
+    symbol="BTC-USDT",
+    trigger_type="stop_loss",
+    side="sell",
+    qty="0.01",
+    trigger_price="83000",
+    order_type="market",
+    max_slippage_bps=50,
+)
+```
+
+A standalone trailing stop may sell or buy. A buy trailing stop tracks the
+lowest price and fires when the price rises the trailing distance from it.
+It requires `limit_price`, its maximum price: the most its child pays per
+unit (a 9-decimal string or `Decimal`, or `Price.from_ticks` for ticks),
+fixed at create. A sell trailing stop takes no `limit_price`.
+
+```python
+await client.triggers.create(
+    symbol="BTC-USDT",
+    trigger_type="trailing_stop",
+    side="buy",
+    qty="0.01",
+    trailing_distance_bps=100,
+    limit_price="85000",
+)
+```
+
+Trigger reads show a buy trailing stop with `side="buy"`,
+`order_type="limit"`, `time_in_force="ioc"` and its maximum price as
+`limit_price`; `details.trailing.trough_price` is the lowest price tracked so
+far (`peak_price` for a sell).
+
+Stop-loss, take-profit and trailing-stop triggers, standalone or attached to
+an order, watch the last trade price unless `trigger_price_source` names
+another: `"last"`, `"index"` or `"mark"`. Reads report the same label
+(`Trigger.trigger_price_source`, `RiskLeg.trigger_price_source`,
+`TrailingStop.trigger_price_source`), so a leg read from an order can be
+passed back to create or modify unchanged. The API rejects a source the pair
+does not support.
+
+```python
+await client.triggers.create(
+    symbol="BTC-USDT",
+    trigger_type="stop_loss",
+    side="sell",
+    qty="0.01",
+    trigger_price="83000",
+    trigger_price_source="index",
+)
+```
+
 When modifying a trigger, omit `activation_price` / `max_slippage_ticks` /
 `max_slippage_bps` to preserve the current values. Send an explicit zero
 (`Price.from_ticks(0)` or `0`) to clear an existing activation price or
@@ -632,6 +702,29 @@ default applies; allowed ranges are enforced by each API, not a global SDK cap.
 Response fields named `ts_ns` are treated as epoch nanoseconds per the API
 contract.
 
+`get_trades()` lists trades newest first. Narrow it with `start_time` /
+`end_time` (inclusive), `side` (`"buy"` or `"sell"` aggressor), and page with
+`page_token=result.next_page_token`.
+
+To backfill trades a live stream missed, walk by trade ID instead: oldest
+first and gap-free. Start from `after_trade_id=0` (or the last trade ID you
+hold) and pass each result's `next_after_trade_id` to the next call. Every
+trade up to `complete_through_trade_id` is returned, across trade-ID epoch
+ends (`epoch_ends`). When `next_after_trade_id` equals the ID you sent,
+nothing newer is available yet; retry later with backoff. `after_trade_id`
+cannot be combined with the time range, side or page token.
+
+```python
+after = 0
+while True:
+    page = await client.market_data.get_trades(symbol="BTC-USDT", after_trade_id=after, limit=1000)
+    for trade in page.trades:
+        handle(trade)
+    if page.next_after_trade_id == after:
+        break  # caught up; resume later from `after`
+    after = page.next_after_trade_id
+```
+
 `get_candles()` returns row-oriented candles newest-first (an incomplete open
 candle, when requested, is prepended). `get_candles_columns()` normalizes its
 column response oldest-first. Sort explicitly by `ts_sec` before feeding a
@@ -654,7 +747,8 @@ async with sub:
 
 - Realtime is binary-only. The client negotiates the `centrifuge-protobuf`
   WebSocket subprotocol and consumes protobuf publications from `:proto`
-  channels. ConnectRPC's optional JSON wire mode does not apply to realtime.
+  channels; live orders use the private WebSocket (see Live orders below).
+  ConnectRPC's optional JSON wire mode does not apply to realtime.
   Inbound WebSocket messages are capped at 4 MiB.
 - Subscription queues are bounded. If the consumer falls behind, the SDK raises
   `PolyesterRealtimeOverflowError` and faults the subscription; it does **not**
@@ -675,6 +769,78 @@ async with sub:
   `client.catalogs.base_quantity_scale_for_symbol_id(order.symbol_id)` (or by
   symbol), then call `quantity.format(scale)`. Never guess or inject scale 8.
 
+### Live orders
+
+`client.orders.subscribe()` streams an account's orders over the private
+WebSocket (`/v1/ws/private`, binary protobuf, subprotocol
+`polyester.v1.proto`). It authenticates with the same realtime tokens as the
+other private streams. One connection carries every account, and each account
+has one server subscription shared by all of its consumers.
+
+```python
+from polyester.models import (
+    PrivateOrdersConnected,
+    PrivateOrdersDisconnected,
+    PrivateOrdersError,
+    PrivateOrdersReady,
+    PrivateOrdersSnapshot,
+    PrivateOrdersStale,
+    PrivateOrdersUnit,
+)
+
+orders = {order.order_id: order for order in (await client.orders.list_open()).orders}
+subscription = await client.orders.subscribe()  # default_account_id, or account_id=...
+async with subscription:
+    async for event in subscription:
+        if isinstance(event, PrivateOrdersReady):
+            # The stream now reflects every order read made before the subscribe.
+            print("ready")
+        elif isinstance(event, PrivateOrdersSnapshot):
+            # The full live view: replace local state.
+            orders = {order.order_id: order for order in event.orders}
+        elif isinstance(event, PrivateOrdersUnit):
+            for order in event.orders:
+                orders[order.order_id] = order  # keep the higher version
+            for order_id in event.removed_order_ids:
+                orders.pop(order_id, None)  # left the live view; not a cancel
+            for change in event.events:
+                print(change)  # PrivateOrderEvent or PrivateOrderCommandOutcome
+        elif isinstance(event, PrivateOrdersStale):
+            print("stale" if event.stale else "caught up")
+        elif isinstance(event, PrivateOrdersError):
+            print(f"recovering from {event.kind}: {event.error}")
+```
+
+- `subscribe()` returns once the server confirmed the subscription; the first
+  event is `PrivateOrdersConnected`. A failure before that raises (for
+  example `PolyesterAuthError` for a refused token, or
+  `PolyesterRealtimeError` with `code == "FORBIDDEN"`).
+- Orders are the same `Order` model the order reads return. Two copies with
+  the same `version` are identical, and a higher `version` is newer. To merge
+  with a read: read `list_open()`, subscribe, wait for `PrivateOrdersReady`,
+  and keep the higher version of each order.
+- `PrivateOrdersReady` means the subscription reached the account's read
+  boundary, sampled when the server received the subscribe: from then on it
+  reflects every acknowledgement given before the subscribe. Wait for it
+  before relying on the stream. It comes once per server subscription, so
+  again after a resubscribe or reconnect, and a consumer that joins an
+  account that is already ready gets it right after its catch-up snapshot.
+- A sequence gap, an expired token or a dropped connection resumes from the
+  last applied position. Consumers see `PrivateOrdersDisconnected` and then
+  `PrivateOrdersConnected`; a position the server can no longer resume is
+  answered with a fresh `PrivateOrdersSnapshot` that replaces local state.
+  Outcomes between the two states are not replayed; fills stay readable from
+  trade history.
+- `PrivateOrdersStale(stale=True)` means the account's live view is
+  temporarily behind; it recovers by itself.
+- Recoverable failures arrive as `PrivateOrdersError` events and through
+  `set_on_error(...)`. A failure that ends the stream (a refused token, a
+  revoked permission, close code 4400 or 4403) is raised from iteration, with
+  `PolyesterRealtimeError.code` or `.close_code` set.
+- Batch-replace progress has no stream: poll
+  `client.orders.get_batch_replace_status(...)` and watch each order's
+  revisions on this stream.
+
 ## Sync client
 
 The sync `Polyester` client exposes the same service tree and constructor