docs: 100% accuracy pass for v4.1.0

[TexasCoding]

Summary

100% docs accuracy pass for v4.1.0 — documents every 4.1.0 addition in the hand-written docs (mkdocstrings auto-renders the models on the reference page, but the resource pages, tables, and examples are hand-maintained).

Changes

• communications.md — new block_trade_proposals sub-resource: quick-reference rows, a worked example section (with the centi-cents/centicounts gotcha), and BlockTradeProposalsResource / AsyncBlockTradeProposalsResource mkdocstrings directives. Documents the new min_ts / max_ts quote filters. Fixes a pre-existing verb error — quotes.accept / quotes.confirm are PUT, not POST (matches the code and METHOD_ENDPOINT_MAP).
• account.md — volume_progress() quick-ref row + section.
• events.md — the new tickers filter (example + prose).
• perps.md — MarginMarket mark-price fields (settlement_mark_price / liquidation_mark_price / reference_price) + the new TickerPrice model; the now-required MarginPosition.subaccount.
• reference.md / request-models.md — new request models in the curated lists / inventory.

Verification

• uv run --group docs mkdocs build --strict ✓ (all new mkdocstrings directives resolve)

Generated from a parallel docs-audit pass against the merged 4.1.0 code; websockets.md was audited and intentionally left unchanged (ErrorPayload.market_tickers auto-renders on the reference page).

🤖 Generated with Claude Code

[claude]

Code Review -- docs: 100% accuracy pass for v4.1.0

Overall: Clean documentation-only PR. The new content is accurate, code examples match the implementation, and the POST->PUT verb fix is a genuine correctness improvement. No blocking issues.

---

Correctness checks (verified against source)

POST -> PUT fix (quotes.accept / quotes.confirm) - PASS
Code at resources/communications.py uses self._put() for both endpoints. The old POST in the docs was wrong; this fix is correct.

Block trade proposals examples - PASS

• block_trade_proposals.create() kwargs match ProposeBlockTradeRequest required fields.
• resp.block_trade_proposal_id correctly references ProposeBlockTradeResponse.block_trade_proposal_id.
• block_trade_proposals.accept(proposal_id) with no body is valid since all kwargs default to None.
• proposal.id, .buyer_accepted, .seller_accepted exist on BlockTradeProposal.

volume_progress() example - PASS
Method exists at resources/account.py:29.

---

Minor issues

1. Path parameter inconsistency (communications.md quick-ref table)
The block_trade_proposals.accept row shows {id} in the URL, but every other row uses the actual named path parameter (e.g. {quote_id}). The SDK positional arg is block_trade_proposal_id, so {block_trade_proposal_id} would be consistent -- unless the OpenAPI spec literally uses {id}, in which case a note clarifying the discrepancy would help.

2. expiration_ts example passes a bare string (communications.md)
Pydantic accepts ISO 8601 strings for AwareDatetime so this works, but a datetime object would be more idiomatic. Low priority -- the current form is not wrong.

3. Wire-format detail leaks into user docs (events.md)
The phrase "joined comma-separated on the wire" exposes an internal transport concern. Consider simplifying to: Pass a list[str] or a single pre-joined string.

---

Nits

• The info callout (centi-cents/centicounts gotcha) is well-placed and will save users real debugging time.
• AsyncBlockTradeProposalsResource mkdocstrings directive is correctly placed after the sync block, matching the existing file pattern.
• min_ts / max_ts described as filtering by last-updated timestamp matches updated_ts on QuoteResponse. Accurate.

---

Summary: Ready to merge with optional polish on items 1-3. The verb fix alone justifies landing this.

[claude]

Code Review — docs: 100% accuracy pass for v4.1.0

Documentation-only PR. I verified every factual claim against the current codebase before commenting.

---

Verified Correct ✅

• Verb fix (POST → PUT) — quotes.accept / quotes.confirm are confirmed PUT in code (communications.py:651,660). This is the most important correction in the PR; the old docs were wrong.
• BlockTradeProposalsResource — all three methods (list/list_all/create/accept) exist and match their table entries. accept uses _post_void → table correctly shows POST.
• ProposeBlockTradeRequest fields — buyer_user_id, seller_user_id, market_ticker, price_centi_cents, centicount: StrictInt = Field(ge=1), maker_side, expiration_ts: AwareDatetime all match (models/communications.py:276).
• expiration_ts="2026-07-01T00:00:00Z" in the example — the create() overload accepts datetime | str, so the string form works. The Z suffix makes it timezone-aware as required.
• Centi-cents / centicounts callout — accurate; both fields are StrictInt with ge=1, no _dollars/_fp aliasing.
• MarginMarket mark-price fields — settlement_mark_price, liquidation_mark_price, reference_price are all TickerPrice | None = None in perps/models/markets.py:102-104.
• TickerPrice shape — price: DollarDecimal, ts_ms: int. Correct.
• MarginPosition.subaccount — required int (no default) at perps/models/portfolio.py:54. "Required" language in the docs is accurate.
• volume_progress() — AccountVolumeProgress.volume_progress is list[AccountApiUsageLevelVolumeProgress]; computed_ts: int (Unix seconds); trailing_30d_volume / earn_volume_goal / keep_volume_goal are FixedPointCount (→ Decimal). All match.
• tickers filter — in events.list() / events.list_all() at resources/events.py:91.
• min_ts / max_ts — in quotes.list() / quotes.list_all() at resources/communications.py:479.
• reference.md / request-models.md — ProposeBlockTradeRequest and AcceptBlockTradeProposalRequest exist in models/communications.py.
• mkdocstrings directives — all four new ::: blocks point to classes that exist.

---

Minor Suggestions

1. TickerPrice import path not mentioned (perps.md)

There are two structurally identical TickerPrice classes — kalshi.perps.models.markets.TickerPrice (REST) and kalshi.perps.ws.models.ticker.TickerPrice (WS). The docs refer to it as "a new model" without a fully-qualified name or import example. Since both are exported and identical, it's not broken, but users who want to type-hint against it will need to hunt. A one-liner import note would help:

from kalshi.perps import TickerPrice  # or kalshi.perps.ws.models import TickerPrice

2. AcceptBlockTradeProposalRequest in request-models.md could be clarified

The table shows block_trade_proposals.accept → AcceptBlockTradeProposalRequest, but the method signature shows the request body is entirely optional (no subtrader/subaccount → empty body). Users skimming the table may think the request model is always required. A note like "(body optional — omit if trading from default account)" inline in the table would prevent confusion.

3. trailing_30d_volume_fp wire name not surfaced (account.md)

The field is trailing_30d_volume_fp on the wire but trailing_30d_volume in the SDK (via AliasChoices). The docs describe the SDK name only, which is fine and consistent with how other _fp fields are documented elsewhere. Just flagging it in case a user hits a raw-response mismatch and looks here first.

---

Overall

This is a clean, accurate, and thorough documentation pass. The verb fix alone makes it worth merging. All new sections are factually grounded against the v4.1.0 code. The centi-cents/centicounts callout is especially valuable for an API that diverges from the rest of the SDK's price conventions.

The suggestions above are all minor nits — none of them block merging.

Verdict: LGTM ✅