docs+polish: env-vars NameError, stale docs, limits default, WS perf, cancel idempotency, events default; populate_by_name on WS; AwareDatetime on REST

docs/concepts.md

@@ -46,6 +46,29 @@ The Kalshi API returns prices as JSON strings with a `_dollars` suffix
 (`yes_bid_dollars: "0.5600"`). The SDK maps these to short field names
 (`yes_bid: Decimal("0.5600")`). Both directions round-trip.
 
+## Datetime semantics
+
+REST response models type every server-emitted timestamp as
+`pydantic.AwareDatetime` — Pydantic v2's tz-aware-only variant of
+`datetime`. Kalshi's wire format is always RFC3339 with `Z` (UTC), so
+live parsing is unaffected. The win is at construction time: tests and
+fixtures that build a model directly **must** pass a tz-aware value, or
+the model raises `ValidationError`. This catches naive `datetime.now()`
+slipping into trading code, where tz arithmetic bugs would otherwise
+corrupt expiration / settlement calculations.
+
+```python
+from datetime import datetime, UTC
+
+Order(... created_time=datetime.now(UTC))                  # OK
+Order(... created_time=datetime(2026, 1, 1, tzinfo=UTC))   # OK
+Order(... created_time=datetime.now())                     # ValidationError — naive
+```
+
+WebSocket payload timestamps (`kalshi.ws.models.*`) currently keep the
+bare `datetime` annotation; the AwareDatetime upgrade for WS models is a
+separate, future change.
+
 ## Cents vs dollars
 
 A few fields are **integer cents**, not dollars:

docs/configuration.md

@@ -40,7 +40,7 @@ with KalshiClient(key_id="...", private_key_path="...", config=config) as client
 | `ws_base_url` | `wss://api.elections.kalshi.com/trade-api/ws/v2` | WebSocket base URL. |
 | `ws_max_retries` | `10` | Maximum reconnect attempts before the WS gives up. |
 | `http2` | `False` | Enable HTTP/2 (requires `httpx[http2]` install extra). |
-| `limits` | `httpx.Limits()` defaults | Connection-pool limits passed straight to `httpx`. |
+| `limits` | `None` | Connection-pool limits passed to `httpx`. When `None`, the underlying `httpx.Client` uses its own pool defaults. Pass an `httpx.Limits(...)` to tune. See [Performance](websockets.md#performance) for WS sizing guidance. |
 
 See [Retries & idempotency](retries.md) for what `max_retries`,
 `retry_base_delay`, `retry_max_delay` do at runtime.

docs/environment-variables.md

@@ -43,10 +43,9 @@ import os
 from kalshi import KalshiClient, KalshiConfig
 
 config = (
-    KalshiConfig.demo() if os.getenv("KALSHI_DEMO", "").lower() == "true"
-    else KalshiConfig.production()
+    KalshiConfig.demo(timeout=10.0, max_retries=5) if os.getenv("KALSHI_DEMO", "").lower() == "true"
+    else KalshiConfig.production(timeout=10.0, max_retries=5)
 )
-config = dataclasses.replace(config, timeout=10.0, max_retries=5)
 with KalshiClient.from_env(config=config) as client:
     ...
 ```

docs/migration.md

@@ -329,8 +329,8 @@ hardening.
 
 ## From `kalshi_python_async`
 
-If you're coming from `kalshi_python_async` (the predecessor community
-client referenced in the project README), this page summarizes the
+If you're coming from the predecessor community client `kalshi_python_async`,
+this page summarizes the
 v1 SDK differences you'll hit. **If you don't recognize that name, you can
 skip this page** — there's nothing here that applies to a greenfield
 project on `kalshi-sdk`.

docs/resources/api-keys.md

@@ -82,6 +82,20 @@ new_pem = new.private_key.get_secret_value()
 client.api_keys.delete("old-key-id")
 ```
 
+!!! info "Delete is not server-idempotent"
+    `delete(api_key)` propagates a 404 as `KalshiNotFoundError` when the
+    key has already been revoked or never existed. The SDK does **not**
+    swallow it — the caller owns safe-retry idempotency:
+
+    ```python
+    from kalshi.errors import KalshiNotFoundError
+
+    try:
+        client.api_keys.delete(key_id)
+    except KalshiNotFoundError:
+        pass  # already revoked — idempotent
+    ```
+
 ## Reference
 
 ::: kalshi.resources.api_keys.ApiKeysResource

docs/resources/communications.md

@@ -117,6 +117,21 @@ client.communications.create_quote(
 )
 ```
 
+!!! info "Delete is not server-idempotent"
+    `delete_rfq(rfq_id)` and `delete_quote(quote_id)` propagate a 404 as
+    `KalshiNotFoundError` when the RFQ or quote is already canceled,
+    expired, or never existed. The SDK does **not** swallow it — the caller
+    owns safe-retry idempotency:
+
+    ```python
+    from kalshi.errors import KalshiNotFoundError
+
+    try:
+        client.communications.delete_rfq(rfq_id)
+    except KalshiNotFoundError:
+        pass  # already canceled — idempotent
+    ```
+
 ## RFQ statuses
 
 `open`, `accepted`, `confirmed`, `canceled`. Status filtering accepts these