docs: accuracy review + release prep for 3.2.0

[TexasCoding]

Prepares the repo for the 3.2.0 release: a full multi-agent documentation accuracy review (12 agents, each verifying a doc slice against the current code) plus the CHANGELOG/metadata finalization the release workflow needs.

Documentation corrections (verified against code)

Doc	Fix
retries.md	Complete retryable status codes (408/425/429/500/502/503/504/520-524); drop PATCH (never issued)
environment-variables.md	KALSHI_DEMO is exact true only (not 1/yes/on); add KALSHI_PRIVATE_KEY_PASSPHRASE + full KALSHI_PERPS_* / KALSHI_KLEAR_* sections
resources/markets.md	candlesticks/bulk_candlesticks return lists (iterate directly); remove nonexistent series_ticker; correct the *_ts filter names
resources/series.md	forecast_percentile_history returns a list
resources/subaccounts.md	list_balances().subaccount_balances; balance is DollarDecimal, no portfolio_value
resources/multivariate.md	lookup_tickers requires auth; deprecation admonition for the 3 legacy methods
websockets.md	user_orders uses DROP_OLDEST; clarify v3.20.0 spec sync = SDK v3.1.0
perps.md	Add KALSHI_PERPS_PRIVATE_KEY_PASSPHRASE + KALSHI_PERPS_WS_BASE_URL
authentication.md	Note KalshiClient.from_env() has no password= kwarg
dataframes.md	Describe the column-oriented (#264) build accurately

(One reviewer finding — "6 vs 8 perps WS channels" — was a false positive: 6 user-facing subscribe_* channels is correct; the agent counted the 2 meta-channels.)

Release prep

• CHANGELOG 3.2.0 now documents the ws_base_url/password kwargs + new env vars, the unified list-envelope null-handling across both surfaces, and a ### Fixed section for the KalshiWebSocket._stop() exception-retrieval fix.
• pyproject description mentions the Perps API; ROADMAP adds shipped v3.0.1/v3.1.0/v3.2.0; RELEASING.md notes the CHANGELOG-header version match.

Verification

• Docs-only — no code changed (the suite was green at 3660 on the last run).
• mkdocs build --strict is clean.
• Version is consistent at 3.2.0 across pyproject.toml, kalshi/__init__.py, and the ## 3.2.0 CHANGELOG heading.

After this merges, the repo is a v3.2.0 tag push away from release (per docs/RELEASING.md).

🤖 Generated with Claude Code

[claude]

Code Review — docs: accuracy review + release prep for 3.2.0

Summary: Docs-only PR correcting factual errors against the current codebase and finalising the 3.2.0 release metadata. I spot-checked every material claim against the live code.

---

Verified accurate ✅

All of the following are confirmed correct against the source:

Doc change	Verified by
KALSHI_DEMO accepts only "true" (case-insensitive), not 1/yes/on	client.py:201 — os.environ.get("KALSHI_DEMO", "").lower() == "true"
Retryable codes: 408/425/429/500/502/503/504/520–524	_base_client.py:40 — RETRYABLE_STATUS_CODES set literal
Drop PATCH from never-retry table	_base_client.py:42 — RETRYABLE_METHODS = {"GET", "HEAD", "OPTIONS"}
resp.subaccount_balances (not .balances), DollarDecimal balance, no portfolio_value	models/subaccounts.py:52,61
Market *_ts filters renamed (min_created_ts, min_updated_ts, min_settled_ts, …)	resources/markets.py:53-59
series_ticker removed from bulk_candlesticks example	resources/markets.py:423 — the public method has no series_ticker param
candlesticks() / forecast_percentile_history() return lists directly	resources/markets.py:331, resources/series.py:163
lookup_tickers requires auth	resources/multivariate.py:253 — self._require_auth()
user_orders moved to DROP_OLDEST	ws/client.py:821-826 — OverflowStrategy.DROP_OLDEST

---

Bug introduced — websockets.md backpressure table 🔴

The order_group_updates channel was removed from the ERROR row but it still uses OverflowStrategy.ERROR in the code:

# ws/client.py:833-834
"order_group_updates",
overflow=OverflowStrategy.ERROR, maxsize=maxsize,

It is also in sequence.py:11 as a SEQUENCED_CHANNEL alongside orderbook_delta. A dropped delta from order_group_updates corrupts stateful order-group tracking the same way a dropped orderbook_delta corrupts the book — so ERROR is correct.

Fix needed:

-| `ERROR` | Stateful, sequenced feeds: `orderbook_delta` | A dropped delta corrupts the locally-reconstructed book. … |
+| `ERROR` | Stateful, sequenced feeds: `orderbook_delta`, `order_group_updates` | A dropped delta corrupts derived state. … |

---

Minor observations (non-blocking)

authentication.md placement — the new paragraph ("KalshiClient.from_env() has no password= kwarg…") is inserted immediately before the existing "An explicit password= argument always wins over…" sentence. The existing sentence now reads oddly in context because from_env() doesn't take password= at all. A brief transition ("For clients that do accept it:") would smooth the flow, but this won't confuse an attentive reader.

ROADMAP.md date — v3.2.0 (2026-06-05) is today. If this PR slips past EOD the date will be wrong on merge. Low risk, easy to spot; just flag it.

---

Verdict

One real documentation error to fix (order_group_updates belongs in ERROR, not silently removed). Everything else checked out. Once that table row is restored this is clean to merge.

[claude]

Code Review — PR #421: docs: accuracy review + release prep for 3.2.0

Scope: Docs-only (14 files, +99/-28). No runtime code changed.

---

Verification pass

I cross-checked every factual claim in the diff against the live SDK source. All changes are accurate:

Doc change	Source confirmation
KALSHI_DEMO only recognises "true" (not 1/yes/on)	client.py:201 — os.environ.get("KALSHI_DEMO", "").lower() == "true"
*_ts filter names corrected to min_created_ts, max_created_ts, min_updated_ts, min_close_ts, max_close_ts, min_settled_ts, max_settled_ts	resources/markets.py:53-59
candlesticks() / bulk_candlesticks() return lists, iterate directly	markets.py:343 returns .candlesticks; _bulk_candlesticks_params has no series_ticker
series_ticker removed from bulk_candlesticks example	Absent from _bulk_candlesticks_params signature (lines 117-144)
forecast_percentile_history returns a list	resources/series.py:163,177 — return type list[ForecastPercentilesPoint]
list_balances() → .subaccount_balances, no .balances, no portfolio_value	models/subaccounts.py:61 — GetSubaccountBalancesResponse.subaccount_balances: list[SubaccountBalance]; SubaccountBalance has no portfolio_value
SubaccountBalance.balance is DollarDecimal (dollars), not integer cents	models/subaccounts.py:52
lookup_tickers requires auth	resources/multivariate.py:253,412 — self._require_auth() is called
user_orders uses DROP_OLDEST	ws/client.py:826 — overflow=OverflowStrategy.DROP_OLDEST
Retryable codes expanded to 408,425,429,500,502,503,504,520–524	_base_client.py:40 — RETRYABLE_STATUS_CODES = {408, 425, 429, 500, 502, 503, 504, 520, 521, 522, 523, 524}
PATCH dropped from never-retry row	Not in RETRYABLE_METHODS; never issued by the SDK

---

Observations

All accurate — nothing blocking. A few minor notes:

1. docs/retries.md: Including 500 in the retryable set is a pre-existing design choice (already in RETRYABLE_STATUS_CODES). The docs now faithfully reflect it. Worth a follow-up issue if intentional retry on 500 Internal Server Error is still debated, but that's out of scope here.

2. CHANGELOG.md — ### Fixed section for KalshiWebSocket._stop(): This is the first time this fix is called out in the changelog. It's a real asyncio "Task exception was never retrieved" issue. Correct to document it, and the description is accurate.

3. docs/resources/multivariate.md deprecation admonition: The admonition correctly identifies create_market(), lookup_tickers(), and lookup_history() as deprecated. The auth correction for lookup_tickers (no → yes) is confirmed against the code. Good catch.

4. docs/environment-variables.md: The new Perps and Klear sections are comprehensive and consistent with docs/perps.md. The KALSHI_PERPS_WS_BASE_URL addition addresses the "REST override leaving WS on prod" footgun — well-explained in both places.

5. RELEASING.md: The added note ("The ## <version> heading in CHANGELOG.md must use the same version") is a genuine process clarification — the release workflow extracts the section by that heading. Good hygiene.

---

Summary

This is a well-executed docs accuracy pass. Every correction traces directly to the source code, the false-positive reviewer finding (6 vs 8 WS channels) is called out in the PR body, and the CHANGELOG/RELEASING/ROADMAP entries are consistent and complete. No concerns. ✅ Ready to merge.