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

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

@@ -1,5 +1,116 @@
 # Changelog
 
+## 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.3.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.3.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.3.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.
 
@@ -115,7 +116,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.3.0"
 ```
 
 Realtime (Centrifugo) and on-chain Funding helpers are included by default.
@@ -294,7 +295,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 +366,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 +391,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 +439,14 @@ 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).
 
 `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 +486,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 +558,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 +581,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 +599,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 +624,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).
@@ -731,7 +778,8 @@ 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 +798,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.
@@ -919,8 +976,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 +1029,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).

{polyester_sdk-0.2.0 → polyester_sdk-0.3.0}/README.md

@@ -3,7 +3,7 @@
 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.3.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.
 
@@ -70,7 +70,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.3.0"
 ```
 
 Realtime (Centrifugo) and on-chain Funding helpers are included by default.
@@ -249,7 +249,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);
@@ -317,9 +320,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(
@@ -341,6 +345,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.
 
@@ -372,7 +393,14 @@ 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).
 
 `cancel_all(...)` requests cancellation of every matching order. The result
 lists up to 200 of them, oldest first, in `cancelled_orders` (each with
@@ -412,7 +440,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`).
 
@@ -481,8 +512,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.
@@ -503,7 +535,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(
@@ -519,15 +553,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(
@@ -543,9 +578,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).
@@ -686,7 +732,8 @@ 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(
@@ -705,6 +752,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.
@@ -874,8 +930,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):**
 
@@ -926,4 +983,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).

{polyester_sdk-0.2.0 → polyester_sdk-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "polyester-sdk"
-version = "0.2.0"
-description = "Official Python SDK for Polyester APIs."
+version = "0.3.0"
+description = "Python SDK for the Polyester API with generated protobuf types and ConnectRPC clients."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "Proprietary" }
@@ -22,7 +22,7 @@ classifiers = [
 ]
 dependencies = [
   "base58>=2.1.1",
-  "connectrpc>=0.9.0,<0.11",
+  "connectrpc>=0.10.0,<0.11",
   "cryptography>=42",
   "eth-abi>=5.1",
   "eth-account>=0.13",
@@ -31,6 +31,7 @@ dependencies = [
   "httpx>=0.27",
   "msgspec>=0.18",
   "protobuf>=7.35.0",
+  "pyqwest>=0.5.1",
   "websockets>=15",
 ]
 

{polyester_sdk-0.2.0 → polyester_sdk-0.3.0}/src/polyester/__init__.py

@@ -27,12 +27,15 @@ from polyester.errors import (
     PolyesterApiError,
     PolyesterAuthError,
     PolyesterError,
+    PolyesterNotImplementedError,
     PolyesterRateLimitError,
     PolyesterRealtimeError,
     PolyesterRealtimeOverflowError,
     PolyesterResponseContractError,
     PolyesterRouteNotFoundError,
     PolyesterServerError,
+    PolyesterTimeoutError,
+    PolyesterTimestampSkewError,
     PolyesterTransportError,
     PolyesterValidationError,
     auth_error_code,
@@ -73,6 +76,7 @@ __all__ = [
     "environment_from_name",
     "PolyesterAuthError",
     "PolyesterError",
+    "PolyesterNotImplementedError",
     "PreparedTradingWithdraw",
     "PolyesterRateLimitError",
     "PolyesterRealtimeError",
@@ -80,6 +84,8 @@ __all__ = [
     "PolyesterResponseContractError",
     "PolyesterRouteNotFoundError",
     "PolyesterServerError",
+    "PolyesterTimeoutError",
+    "PolyesterTimestampSkewError",
     "PolyesterTransportError",
     "PolyesterValidationError",
     "is_retryable_error",

{polyester_sdk-0.2.0 → polyester_sdk-0.3.0}/src/polyester/_version.py

@@ -1,3 +1,3 @@
 """Single source for the SDK version string used by packaging and User-Agent."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"