feat(rest): pluggable JSON loader + plumb extra_headers through resources (#260, #253)

docs/concepts.md

@@ -163,6 +163,32 @@ returns the same shapes as `portfolio.*`. Non-FCM accounts get 401/403.
 
 See [FCM](resources/fcm.md).
 
+
+## Per-request headers (Idempotency-Key, tracing)
+
+Every public resource method accepts an ``extra_headers: dict[str, str] | None = None``
+kwarg that lands on the wire for that single call. Use it for per-request
+idempotency keys, distributed-tracing headers, or any one-off header that
+doesn't belong on every request (set those via ``KalshiConfig.extra_headers``).
+
+```python
+import uuid
+
+order = client.orders.create(
+    ticker="KXPRES-24-DJT",
+    side="yes",
+    action="buy",
+    count=1,
+    yes_price="0.65",
+    client_order_id="cli-1",
+    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
+)
+```
+
+Auth headers are sacred: ``KALSHI-ACCESS-KEY`` / ``KALSHI-ACCESS-SIGNATURE`` /
+``KALSHI-ACCESS-TIMESTAMP`` cannot be overridden via ``extra_headers`` — the
+SDK-signed values always win at the transport layer.
+
 ## API key, scope
 
 Authentication identity. Has `read` and `write` scopes; `write` requires

docs/configuration.md

@@ -40,6 +40,9 @@ 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). |
+| `rest_json_loads` | `None` | Optional callable for parsing REST response bodies (e.g. `orjson.loads`). When set, receives `response.content` bytes; falls back to stdlib `json` otherwise. Useful for list-heavy endpoints (`markets.list_all`, `trades.list_all`). |
+| `ws_json_loads` | `None` | Optional callable for parsing WS frames (e.g. `orjson.loads`). |
+| `ws_json_dumps` | `None` | Optional callable for serializing outbound WS commands. |
 | `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`,

kalshi/config.py

@@ -48,6 +48,11 @@ class KalshiConfig:
         ws_ping_interval: Interval (s) between WS keepalive pings. Default 20.
         ws_close_timeout: Time (s) to wait for graceful WS close handshake.
             Default 5.
+        rest_json_loads: Optional callable used to parse REST response
+            bodies. ``None`` falls back to :func:`httpx.Response.json`
+            (stdlib :func:`json.loads`). Set to e.g. ``orjson.loads`` for
+            ~2-3x faster parsing on list endpoints (``markets.list_all``,
+            ``trades.list_all``, ``fcm.orders``).
         ws_json_loads: Optional callable used to parse WS frames. ``None``
             falls back to :func:`json.loads`. Set to e.g. ``orjson.loads``
             for ~2-3x faster recv-loop parsing on high-volume streams.
@@ -68,6 +73,7 @@ class KalshiConfig:
     limits: httpx.Limits | None = None
     ws_ping_interval: float = 20.0
     ws_close_timeout: float = 5.0
+    rest_json_loads: Callable[[bytes], Any] | None = None
     ws_json_loads: Callable[[bytes | str], Any] | None = None
     ws_json_dumps: Callable[[Any], bytes | str] | None = None
     allow_unknown_host: bool = False