[harley-poly]

Changes

Dispatch positionSubscription and accountBalancesUpdate to the advertised position and balance callbacks, preserving existing aliases and the original message object. Ignore empty error strings while retaining nonempty errors.

Correct the payload types and examples for before/after changes and balance snapshots. Include exact decimal quantities, nullable cost fields, combo legs, complete nested team/market metadata and optional balance reservation/display fields. Mark position snapshots as legacy; current position subscriptions send updates only.

BREAKING CHANGE: typed consumers must use the corrected envelope keys and handle nullable values. The README includes migration examples. Set the reviewed package version to 2.0.0 for the existing publish workflow.

Part of ISVBE-936; RFQ callbacks remain outside this PR.

Testing

• 190 tests pass on Python 3.13/websockets 17.1 and Python 3.10/websockets 13.0.
• Real local socket regressions cover position opening/closing, balance updates/snapshots and raw payload identity. Six new callback cases fail with the original dispatcher.
• Existing aliases, empty/nonempty errors and snapshot EOF behavior are covered.
• Typed consumers cover exact fractional quantities, nullable costs, combo/team/market metadata and optional balance fields; the previous models reject these consumers.
• Ruff lint/format, mypy (package, typed consumers and WebSocket example), and wheel/sdist build pass.

Checklist

• Tests pass (pytest)
• Linting passes (ruff check .)
• Types check (mypy polymarket_us)

---

Note

Medium Risk
Breaking change for apps reading old envelope keys; incorrect migration would mis-parse live position and balance streams, though dispatch behavior is heavily tested.

Overview
Ships 2.0.0 so private WebSocket handling matches the current gateway wire format for positions and account balances.

The private dispatcher now routes positionSubscription and accountBalancesUpdate frames to the existing position/balance callbacks (legacy key aliases still work), passes through the raw message unchanged, and treats only non-empty error strings as failures—empty error no longer blocks data callbacks.

Typed payloads are updated: position changes use positionSubscription.beforePosition / afterPosition instead of positionSubscriptionUpdate.position; balance snapshot/update use accountBalancesSnapshot.balances and accountBalancesUpdate.balanceChange with full UserBalance objects. Related models add decimal quantity fields, nullable cost/metadata, combo leg types, and optional balance reservation/display fields. README and the WebSocket example document migration; position snapshots are documented as legacy (initial positions via REST).

Tests add gateway fixtures, socket regressions, alias preservation, and typed consumer coverage.

^{Reviewed by Cursor Bugbot for commit 713b680. Bugbot is set up for automated code reviews on this repo. Configure here.}