polyester-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{polyester_sdk-0.2.0 → polyester_sdk-0.4.0}/CHANGELOG.md

@@ -1,5 +1,188 @@
 # Changelog
 
+## 0.4.0
+
+Git tag: `v0.4.0`. Released 2026-11-02.
+
+**What a trading bot gains.** An order now says why it ended, in the same
+words everywhere. A rejected order's `reject_reason` is the error code the
+Orders API returns for the same refusal, and a canceled order's
+`cancel_reason` says why it was canceled, on order reads and on the private
+order stream alike. Before, the numeric reason used the matching engine's own
+numbering, which clashed with the API's error codes. `OrderbookData.available`
+tells a bot when a book's levels are unknown rather than empty, so it does not
+quote into a book that is being rebuilt. `Trigger.version` picks out the
+newest copy of a trigger, and nine new error codes are definite refusals: the
+request did not apply, so do not resend it unchanged.
+
+This release works on devnet now, and on testnet after testnet's next upgrade.
+
+**Reason labels in this SDK.** `reject_reason` is the `orders.v1.ErrorCode`
+name without its `ERROR_CODE_` prefix, for example `POST_ONLY_CROSS`.
+`cancel_reason` is the `orders.v1.CancelReason` name without its
+`CANCEL_REASON_` prefix, for example `USER_REQUEST`. The Go and Rust SDKs
+format these labels differently.
+
+**Breaking changes**
+- The `whiteboard`, `polychart` and `layout` services are removed.
+- The generated `orders.v1.Order` loses `terminal_reason_code` and
+  `terminal_reason`, and the generated `privatews.v1.OrderEvent` loses
+  `reason_code`. Read `Order.reject_reason` and `Order.cancel_reason` instead.
+- `PrivateOrderEvent.reason_code` is replaced by `reject_reason` and
+  `cancel_reason`.
+- `sub_accounts.get()` no longer takes `include_balances`.
+
+### Breaking
+- The `whiteboard`, `polychart` and `layout` services are removed from the
+  client, because those APIs are no longer part of the public API.
+- An order's terminal reason code and name are removed: the generated
+  `orders.v1.Order` no longer has `terminal_reason_code` or `terminal_reason`,
+  and the generated `privatews.v1.OrderEvent` no longer has `reason_code`.
+  Their numbers did not match the Orders API's error codes. Read the typed
+  `Order.reject_reason` and `Order.cancel_reason` instead (see Added).
+- `PrivateOrderEvent.reason_code` is replaced by `reject_reason` and
+  `cancel_reason`. A rejected order's event names its refusal as the order
+  write API does (for example `POST_ONLY_CROSS`). A canceled order's event
+  names why it ended (for example `USER_REQUEST`), and so does the replaced
+  event of the order a replace ended (`REPLACED`). Both are `None` otherwise.
+- `sub_accounts.get()` no longer takes `include_balances`: a sub-account read
+  no longer returns balances. Read them with `balances.list()` for the
+  sub-account.
+
+### Added
+- `Order.reject_reason` and `Order.cancel_reason`, on order reads and on the
+  orders of the private order stream's snapshots and units. A rejected order
+  carries the error code the Orders API returns for the same refusal (for
+  example `INSUFFICIENT_FUNDS`); a canceled order carries why it ended (for
+  example `USER_REQUEST`, `IOC_REMAINDER`, `STP_EXPIRE_MAKER`, `REPLACED` or
+  `GTD_EXPIRED`). Both are `None` for every other status, and on servers that
+  do not send them yet. An unknown number reads `UNKNOWN_ERROR_CODE(n)` or
+  `UNKNOWN_CANCEL_REASON(n)` instead of raising.
+- `OrderbookData.available`. When `False`, the book is being built or was
+  invalidated: its levels are unknown, not empty, so request the snapshot
+  again later. A subscription's book reports the value of the last snapshot
+  it applied; deltas, resets included, do not change it.
+- `Trigger.version`: 1 for a trigger's first state, higher for every later
+  state change. Keep the copy with the highest version across reads and
+  realtime updates. It is `0` from a server that does not send it.
+- Order error codes `ATTACHED_LEGS_EXCEEDED`, `FEE_ASSET_INVALID`,
+  `FEE_CEILING_INVALID`, `UNSUPPORTED_FIELD_SET`,
+  `TRIGGER_FIRE_LIMIT_REACHED`, `CONDITION_FLAGS_INVALID`,
+  `CONDITION_PARAMETER_SET`, `TWAP_CAPACITY_REACHED` and
+  `CHILD_ORDER_INCONSISTENT`. Each raises a non-retryable `PolyesterApiError`
+  and is a definite refusal: the request did not apply.
+
+## 0.3.0
+
+Git tag: `v0.3.0`. Released 2026-10-31.
+
+**What a trading bot gains.** `trades.subscribe()`, `transfers.subscribe()`,
+`triggers.subscribe_events()` and `market_data.subscribe_trades()` now yield
+every event; before, the rest of each batch was dropped or garbled. Spot
+config and the catalog expose each pair's order limits, including the new cap
+on one market order's notional, so a bot can size orders before it sends
+them. Rejections are easier to act on: a duplicate client order ID names the
+order that already holds it, a clock-skew rejection is the retryable
+`PolyesterTimestampSkewError`, and a bad key or signature is a non-retryable
+`PolyesterAuthError` instead of a retryable server error. Replacement orders
+report the quantity they inherited, and slippage caps and trigger inputs are
+checked before sending the way the API checks them. The SDK now requires
+`connectrpc` 0.10.
+
+This release works on devnet today, and on testnet after testnet's next
+upgrade, which brings the new private order stream.
+
+**Breaking changes**
+- `triggers.modify()` no longer takes `limit_price`.
+- `max_slippage_bps` is at most 9999 for a market order that sells, a sell
+  stop-loss or take-profit market child, every trailing stop and
+  `triggers.modify()`.
+- `trigger_price_source="mark"` raises `PolyesterValidationError`.
+- A buy trailing stop's `limit_price` must be at least its `activation_price`.
+- API-key rejections from the API gateway raise the retryable
+  `PolyesterTimestampSkewError` or the non-retryable `PolyesterAuthError`
+  instead of a retryable `PolyesterServerError`.
+
+### Breaking
+- `triggers.modify()` no longer takes `limit_price`: the API rejects any
+  change to a child's limit price. Cancel the trigger and create a new one.
+- Slippage caps match the API: `max_slippage_bps` is 1–9999 for a market
+  order that sells, a sell stop-loss or take-profit market child, every
+  trailing stop (standalone or attached, either side) and `triggers.modify()`.
+  Buy market orders, buy stop-loss or take-profit market children and TWAP
+  slices still accept 10000.
+- `trigger_price_source="mark"` raises `PolyesterValidationError`: spot
+  markets have no mark price. Use `"last"` or `"index"`.
+- A buy trailing stop's `limit_price` must be at least its `activation_price`.
+- API-key rejections from the API gateway are classified by their code.
+  `TIMESTAMP_SKEW` raises the new retryable `PolyesterTimestampSkewError`;
+  retrying signs the request again with a fresh timestamp, and the request
+  never reached a service, so `mutation_outcome_unknown()` is false. Other
+  codes such as `SIGNATURE_INVALID`, `KEY_DISABLED` or `IP_NOT_ALLOWED`
+  raise a non-retryable `PolyesterAuthError` carrying the code. Earlier
+  versions reported all of them as a retryable `PolyesterServerError`
+  without details.
+
+### Added
+- Spot config order limits: `SpotConfig.pair_order_limits` and
+  `client.catalogs.order_limits_for_symbol(...)` / `order_limits_for_symbol_id(...)`
+  return `PairOrderLimits` with `max_limit_qty_base`, `max_market_qty_base`
+  and `max_order_notional_quote` (decimal strings, `None` when the pair has
+  no maximum) and `max_open_orders_per_pair`. `SpotConfig.max_open_orders_total`
+  and `client.catalogs.max_open_orders_total` give the cross-pair limit. The
+  open-order counts are venue defaults; an account may have a lower limit.
+- `PairOrderLimits.max_market_notional_quote`: the largest notional of one
+  market order in quote units, valued at a buy's protection price or a sell's
+  reference price. A larger market order is rejected with `MAX_NOTIONAL`.
+  `None` means the pair has no cap. Available on `SpotConfig.pair_order_limits`
+  and `client.catalogs.order_limits_for_symbol(...)`.
+- `Order.inherited_cum_qty`: the filled quantity a replacement order carries
+  over from its predecessors.
+- `action_taken` on batch replace admission and status items: `"replaced"`
+  when a successor was admitted, `"amended"` for a cancel-only outcome.
+- `existing_order_id` on a `CONFLICT_DUPLICATE_CLIENT_ORDER_ID` rejection,
+  when the server knows the order: `PolyesterApiError.existing_order_id` on a
+  single create and `BatchCreateResultItem.existing_order_id` on a batch
+  create item.
+- `triggers.modify()` and `triggers.resume()` no longer need `symbol` or
+  `symbol_id`; without one they target the trigger's own market. An API key
+  limited to specific markets must still pass it.
+- `LedgerTransfer.transfer_id`, the unsigned 128-bit decimal shared by both
+  legs of a transfer.
+- `VIPStatus.settled_volume_quality` and `average_aop_quality`
+  (`VIPMetricQuality`: `status` of `complete`, `price_unavailable` or
+  `incomplete_history`, plus `incomplete_hours`).
+- `TriggerTrailingDetails.trigger_price`, the current trailing threshold.
+- `AsyncRealtimeClient.subscribe_proto_batch(...)` for channels whose
+  publications batch several events.
+- A Connect `deadline_exceeded` raises `PolyesterTimeoutError`, a subclass of
+  `PolyesterTransportError`, so existing handlers still catch it.
+- HTTP 501 and Connect `unimplemented` raise `PolyesterNotImplementedError`,
+  a `PolyesterApiError` subclass that `PolyesterRouteNotFoundError` now
+  extends.
+
+### Fixed
+- `trades.subscribe()`, `transfers.subscribe()`, `triggers.subscribe_events()`
+  and `market_data.subscribe_trades()` decode the batched publications these
+  channels now send and yield each event on its own, in order. Earlier
+  versions decoded a batch as one event, which dropped or garbled the rest of
+  it. An event that fails to decode is reported through `set_on_error(...)`
+  without dropping the rest of its batch.
+- `market_overview.create_subscription(symbols=[...])` keeps only the
+  requested markets in live and buffered updates; earlier versions filtered
+  the initial snapshot only.
+- `trades.list(after_match_id=...)` rejects a value beyond the uint64 range
+  before sending.
+
+### Changed
+- `connectrpc` minimum raised from 0.9.0 to 0.10.0. 0.9.0 has no
+  `connectrpc.codec`, so the SDK failed to import with it.
+- The package description now reads "Python SDK for the Polyester API with
+  generated protobuf types and ConnectRPC clients."
+
+### Internal
+- `sdk-capabilities.json` no longer carries `publicDescriptorSha256` or `generatedAt`, so a proto publication that only changes `src/polyester/gen/` and `manifest.json` no longer makes it stale; `manifest.json` stays the single source of the descriptor hash.
+
 ## 0.2.0
 
 Git tag: `v0.2.0`.

{polyester_sdk-0.2.0 → polyester_sdk-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: polyester-sdk
-Version: 0.2.0
-Summary: Official Python SDK for Polyester APIs.
+Version: 0.4.0
+Summary: Python SDK for the Polyester API with generated protobuf types and ConnectRPC clients.
 Project-URL: Homepage, https://github.com/Fabric-Labs/polyester-sdk-python
 Project-URL: Documentation, https://polyester.com/docs/sdk/python/get-started/overview
 Project-URL: Repository, https://github.com/Fabric-Labs/polyester-sdk-python
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: base58>=2.1.1
-Requires-Dist: connectrpc<0.11,>=0.9.0
+Requires-Dist: connectrpc<0.11,>=0.10.0
 Requires-Dist: cryptography>=42
 Requires-Dist: eth-abi>=5.1
 Requires-Dist: eth-account>=0.13
@@ -28,6 +28,7 @@ Requires-Dist: eth-utils>=5.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: msgspec>=0.18
 Requires-Dist: protobuf>=7.35.0
+Requires-Dist: pyqwest>=0.5.1
 Requires-Dist: websockets>=15
 Provides-Extra: chain
 Provides-Extra: dev
@@ -48,7 +49,7 @@ Description-Content-Type: text/markdown
 Official Python SDK for Polyester APIs, built for trading bots, backend jobs,
 research notebooks, and automation.
 
-**Status:** `0.2.0`, pre-1.0: a minor release may include breaking changes (see
+**Status:** `0.4.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.
 
@@ -88,7 +89,6 @@ Requires **Python 3.11+**.
 | Zipper deposit-withdraw config | Yes |
 | Chain analytics | Yes |
 | Lifecycle flows | Yes |
-| Polychart / layout / whiteboard | Yes |
 | Realtime account and market streams | Yes |
 | Reference catalogs + wait-for-ready | Yes |
 | Qty / price decimal + scaled-int inputs | Yes |
@@ -103,8 +103,8 @@ Full cross-language comparison:
 <!-- sdk-capabilities:end -->
 
 Rows marked **Yes** mean that an SDK wrapper exists; deployment authorization
-still applies. In particular, whiteboard/social-verification and some
-layout/polychart routes may require a JWT session or may not be mounted.
+still applies. In particular, social-verification routes may require a JWT
+session or may not be mounted.
 Private streams require an Account ID and the corresponding API-key permission.
 A successful subscribe call means the token exchange and realtime handshake
 completed. Treat a structured permission denial as non-transient and update the
@@ -115,7 +115,7 @@ API-key policy before retrying.
 PyPI: https://pypi.org/project/polyester-sdk/
 
 ```bash
-pip install "polyester-sdk==0.2.0"
+pip install "polyester-sdk==0.4.0"
 ```
 
 Realtime (Centrifugo) and on-chain Funding helpers are included by default.
@@ -294,7 +294,10 @@ first attempt admitted the order. After an unknown outcome, look up that id
 (`get` / `list_open`) before creating again. A second create with the same id
 is rejected (`CONFLICT_DUPLICATE_CLIENT_ORDER_ID`) even when the payload
 matches. Only create again with that id if reconciliation shows the first
-attempt did not admit.
+attempt did not admit. When the server knows the order that already holds the
+id, the rejection carries it: `PolyesterApiError.existing_order_id` on a
+single create, `BatchCreateResultItem.existing_order_id` on a batch create
+item (empty otherwise).
 Client order ids accept 1 to 36 ASCII letters, digits, `.`, `_`, `:`, `/`, and
 `-`. Batch create, cancel, and replace accept at most 20 items. `batch_create`
 always sends `request_id` (caller value or a generated `batch-create-*` key);
@@ -362,9 +365,10 @@ prerequisite for order submission.
 
 Market orders are IOC and enforce a slippage-derived execution boundary. See
 [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.
+before overriding pair defaults. Set at most one of `max_slippage_bps` or
+`max_slippage_ticks`. `max_slippage_bps` is 1–10000 for a buy and 1–9999 for a
+sell. Omit both to keep the pair default. The fields are rejected on limit
+orders and if both are supplied.
 
 ```python
 result = await client.orders.create(
@@ -386,6 +390,23 @@ Do **not** pass floats. `ticks` on `Price` means Polyester protocol price units
 (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.
+
+Order limits are read from the spot config. `client.catalogs.order_limits_for_symbol("BTC-USDT")`
+(or `get_spot_config().pair_order_limits`) returns `PairOrderLimits` with
+decimal strings `max_limit_qty_base`, `max_market_qty_base` and
+`max_order_notional_quote` (`None` when the pair has no maximum), and
+`max_open_orders_per_pair`. `max_market_notional_quote` caps the notional of
+one market order, valued at a buy's protection price or a sell's reference
+price (`None` means no cap). `client.catalogs.max_open_orders_total` (or
+`SpotConfig.max_open_orders_total`) is the cross-pair resting-order limit.
+The open-order counts are the venue defaults for a typical account, `0` when
+unpublished; an account may have a lower limit of its own.
+
+```python
+limits = client.catalogs.order_limits_for_symbol("BTC-USDT")
+if limits is not None and limits.max_limit_qty_base is not None:
+    print("largest limit order:", limits.max_limit_qty_base, "BTC")
+```
 `orders.preview_order(...)` remains the authority for balances, reservations,
 liquidity, and other stateful rules.
 
@@ -417,7 +438,31 @@ The predecessor ID can be stale after admission; reconcile the successor IDs
 and per-item phases by polling `get_batch_replace_status`. Use
 `is_batch_replace_settled(status)` only to determine that all items have moved
 to `working`, `rejected`, or `terminal`, not as a finality signal. Retry an
-ambiguous batch request with the same `request_id`.
+ambiguous batch request with the same `request_id`. Each admission and status
+item carries `action_taken`: `"replaced"` when a successor order was admitted,
+`"amended"` for a cancel-only outcome with no successor (keep tracking
+`old_order_id` until it is terminal).
+
+A replacement order's `cum_qty` includes the quantity filled by its
+predecessors; `Order.inherited_cum_qty` is that carried-over part (zero for an
+order never replaced).
+
+An order says why it ended. A `rejected` order's `reject_reason` is the error
+code the Orders API returns for the same refusal, without the `ERROR_CODE_`
+prefix (for example `POST_ONLY_CROSS` or `INSUFFICIENT_FUNDS`). A `canceled`
+order's `cancel_reason` is one of `USER_REQUEST`, `IOC_REMAINDER`,
+`MARKET_REMAINDER`, `STP_EXPIRE_MAKER`, `STP_EXPIRE_TAKER`, `STP_EXPIRE_BOTH`,
+`REPLACED`, `GTD_EXPIRED`, `QTY_AT_OR_BELOW_FILLED`, `PAIR_DRAIN`,
+`ATTACHED_RISK_REFUSED`, `CANCEL_ALL_AFTER`, `ACCOUNT_REPAIR`,
+`TWAP_ROLLOVER`, `STRATEGY_CANCEL` or `SYSTEM`. Both are `None` for every other
+status. A number this SDK does not know yet reads `UNKNOWN_ERROR_CODE(n)` or
+`UNKNOWN_CANCEL_REASON(n)`; treat it as a generic refusal or end.
+
+```python
+order = (await client.orders.get(key=ClientOrderId(client_order_id))).order
+if order is not None and order.reject_reason == "POST_ONLY_CROSS":
+    ...  # reprice and resend
+```
 
 `cancel_all(...)` requests cancellation of every matching order. The result
 lists up to 200 of them, oldest first, in `cancelled_orders` (each with
@@ -457,7 +502,10 @@ Public catalog reads need no credentials. Authenticated VIP status, effective sp
 account trading limits require an API key. `GetVIPStatus` has no subaccount selector: JWT and
 API-key callers receive the owning root group only. USD amounts and fee percents are decimal
 strings. Optional qualification metrics, timestamps, and next-tier thresholds stay omitted
-when unset. `policy_class` uses full protobuf enum names
+when unset. `VIPStatus.settled_volume_quality` and `average_aop_quality` say how complete
+each 30-day metric is: `status` is `complete`, `price_unavailable` (the metric is a lower
+bound) or `incomplete_history`, with `incomplete_hours` out of 720. Both are `None` when the
+assignment carries no qualification evidence. `policy_class` uses full protobuf enum names
 (`TRADING_RATE_LIMIT_CLASS_PLACE` / `_CANCEL`). Rate-limit rules expose
 `vip_tier` (not `tier`).
 
@@ -526,8 +574,9 @@ 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
+slippage cap, `max_slippage_ticks` (Q9 ticks) or `max_slippage_bps` (1–10000
+for a buy, 1–9999 for a sell), 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.
@@ -548,7 +597,9 @@ 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`.
+fixed at create, and at least `activation_price` when that is set. A sell
+trailing stop takes no `limit_price`. Every trailing stop, standalone or
+attached to an order, takes `max_slippage_bps` from 1 to 9999.
 
 ```python
 await client.triggers.create(
@@ -564,15 +615,16 @@ await client.triggers.create(
 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).
+far (`peak_price` for a sell), and `details.trailing.trigger_price` is the
+current threshold.
 
 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
+another: `"last"` or `"index"`. Spot markets have no mark price, so `"mark"`
+raises `PolyesterValidationError`. 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.
+passed back to create unchanged.
 
 ```python
 await client.triggers.create(
@@ -588,9 +640,20 @@ await client.triggers.create(
 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
-maximum-slippage cap. Create/modify `max_slippage_bps` must be 1–10000;
-modify still accepts `0` to clear. Trailing distance in bps uses the same
-1–10000 range; trigger modify accepts `0` to clear.
+maximum-slippage cap. Modify `max_slippage_bps` is 1–9999 (the patch does not
+say what it modifies, so it takes the cap shared by trailing stops and
+sells); `0` clears it. Trailing distance in bps is 1–10000; trigger modify
+accepts `0` to clear. A child's limit price is fixed at create, so `modify`
+takes no `limit_price`: cancel the trigger and create a new one instead.
+
+`triggers.modify(...)` and `triggers.resume(...)` do not need a symbol: without
+`symbol` / `symbol_id` they target the trigger's own market. When given, it
+must be that market, and an API key limited to specific markets must give it.
+
+```python
+await client.triggers.modify(trigger_id=trigger_id, trigger_price="82500")
+await client.triggers.resume(trigger_id=trigger_id)
+```
 
 `orders.list_open(trigger_id=...)` / `orders.list_history(trigger_id=...)`
 return only child orders created by that trigger (TWAP/ladder slices).
@@ -598,6 +661,12 @@ Trigger-event `fire_price` is `None` for time-scheduled TWAP slice fires
 (`fire_price_ticks` is optional on the wire). Canceled and failed triggers
 expose typed `cancel_reason` / `failure_reason` labels (empty when unset).
 
+`Trigger.version` is 1 for a trigger's first state and higher for every later
+state change. Reads and realtime trigger updates carry the same version for
+the same state; list results can lag realtime updates, and an update can
+repeat after a reconnect. Keep the copy of each trigger with the highest
+version and ignore any copy whose version is not higher than the one you hold.
+
 ## Balances: funding vs trading
 
 Ledger balances have separate **funding** and **trading** buckets per asset.
@@ -725,13 +794,27 @@ while True:
     after = page.next_after_trade_id
 ```
 
+`orderbook.get(symbol=...)` returns a depth snapshot. When its `available` is
+`False`, the server is building the book or invalidated it: its levels are
+unknown, not empty, so do not read the empty sides as no liquidity; request
+the snapshot again later. Only a snapshot carries `available`: books from
+`orderbook.create_subscription(...)` report the value of the last snapshot the
+subscription applied, and deltas, resets included, do not change it.
+
+```python
+book = await client.orderbook.get(symbol="BTC-USDT", depth=10)
+if not book.available:
+    ...  # unknown book: retry later instead of quoting into an empty side
+```
+
 `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
 chronological indicator.
 
 Merged market overview stream (snapshot + live updates). The create call waits
-for the WebSocket handshake and initial snapshot:
+for the WebSocket handshake and initial snapshot. With `symbols=[...]`, the
+snapshot and every live or buffered update keep only those markets:
 
 ```python
 sub = await client.market_overview.create_subscription(
@@ -750,6 +833,15 @@ async with sub:
   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.
+- Market trade, user fill (`trades.subscribe`), ledger transfer
+  (`transfers.subscribe`) and trigger event (`triggers.subscribe_events`)
+  channels publish batches. Each event of a batch is yielded on its own, in
+  order. An event that fails to decode is reported through `set_on_error(...)`
+  without dropping the rest of its batch. Both legs of a ledger transfer share
+  `LedgerTransfer.transfer_id`; with `account_code` it identifies a leg, and
+  a repeated leg replaces the earlier copy. A trigger event is identified by
+  `(trigger_id, event_type, child_seq, ts_ns)`. For your own batched channel,
+  use `realtime.subscribe_proto_batch(channel, decode_batch=...)`.
 - Subscription queues are bounded. If the consumer falls behind, the SDK raises
   `PolyesterRealtimeOverflowError` and faults the subscription; it does **not**
   silently drop updates.
@@ -819,6 +911,11 @@ async with subscription:
   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.
+- A `PrivateOrderEvent` says why an order ended, as the order's own fields
+  do: `reject_reason` on `rejected`, and `cancel_reason` on `canceled` and on
+  the `replaced` event of the order a replace ended (`REPLACED`). Both are
+  `None` otherwise, including on the `replaced` event that installs the
+  successor.
 - `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
@@ -919,8 +1016,9 @@ account; those tests may cancel every open order in their selected symbol.
 
 CI requires every public Connect RPC in gen to be wrapped or listed in
 `sdk-coverage.toml`. Contributors: `python scripts/check_sdk_coverage.py`.
-CI refreshes `sdk-capabilities.json` and the README capability table on the
-same branch when they drift (same-repo PRs / pushes to `main`).
+CI fails when `sdk-capabilities.json` or the README capability table is stale;
+refresh both with `python scripts/check_sdk_coverage.py --write-capabilities`
+and commit the result.
 
 **Pre-release checklist (realtime changes):**
 
@@ -971,4 +1069,18 @@ Connect RPC over HTTP via generated clients in `src/polyester/gen/`. Wire format
 defaults to **binary protobuf**; pass `wire_format="json"` for debugging.
 
 Some RPCs may return HTTP 404 on devnet. The SDK raises `PolyesterRouteNotFoundError`
-with a clearer message than `[unimplemented]: Not Found`.
+with a clearer message than `[unimplemented]: Not Found`. HTTP 501 and Connect
+`unimplemented` raise `PolyesterNotImplementedError`, the parent class of
+`PolyesterRouteNotFoundError`; neither is retryable.
+
+API-key rejections from the gateway carry a code. A request whose signed
+timestamp falls outside the server's skew window raises
+`PolyesterTimestampSkewError` (`code == "TIMESTAMP_SKEW"`). It is
+retryable, and the gateway rejected it before any service saw it: a retry
+signs again with a fresh timestamp. If it persists, fix the local clock. For
+large bursts, bound concurrency so requests do not wait locally past the skew
+window. Other gateway codes (`SIGNATURE_INVALID`, `KEY_DISABLED`,
+`IP_NOT_ALLOWED`, ...) raise a non-retryable `PolyesterAuthError` whose
+message is the code. A request whose deadline expires raises `PolyesterTimeoutError`, a
+`PolyesterTransportError`: retryable, but a mutation may still have been
+applied, so reconcile first (`mutation_outcome_unknown(error)` is true).