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

{polyester_sdk-0.1.0a55 → polyester_sdk-0.3.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.3.0}/CHANGELOG.md

@@ -1,6 +1,268 @@
 # Changelog
 
-## Unreleased
+## 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`.
+
+**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