Skip to content

docs(configuration): document total_timeout, ws_ping_interval, ws_close_timeout, allow_unknown_host #304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TexasCoding merged 2 commits into from
May 21, 2026
Merged

docs(configuration): document total_timeout, ws_ping_interval, ws_close_timeout, allow_unknown_host #304

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fbeabeb
docs(configuration): document total_timeout, ws_ping_interval, ws_clo…
TexasCoding May 21, 2026
b51fd82
docs(configuration): regroup total_timeout next to retry knobs; clari…
TexasCoding May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ with KalshiClient(key_id="...", private_key_path="...", config=config) as client
| `max_retries` | `3` | Maximum retry attempts on retryable methods. |
| `retry_base_delay` | `0.5` | Base for exponential backoff (seconds). |
| `retry_max_delay` | `30.0` | Cap on any single retry sleep — also caps `Retry-After`. |
| `total_timeout` | `None` | Wall-clock cap (seconds) across the whole request including all retries. `None` = unbounded; cap with the per-attempt `timeout` only. See [Retries & idempotency](retries.md). |
| `extra_headers` | `{}` | Extra HTTP headers added to every request. Useful for custom User-Agent. |
| `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. |
Expand All @@ -44,6 +45,9 @@ with KalshiClient(key_id="...", private_key_path="...", config=config) as client
| `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. |
| `ws_ping_interval` | `20.0` | Seconds between WebSocket keepalive pings (forwarded to the `websockets` library). |
| `ws_close_timeout` | `5.0` | Seconds to wait for a clean WebSocket close handshake before forcing the socket shut. |
| `allow_unknown_host` | `False` | When `False`, reject `base_url` / `ws_base_url` whose host is not in the Kalshi allowlist (`api.elections.kalshi.com`, `demo-api.kalshi.co`) or a loopback host. Set `allow_unknown_host=True` or `KALSHI_ALLOW_UNKNOWN_HOST=1` to allow it (mock server, proxy, alternate region). (Added in v2.5.0, #250.) |

See [Retries & idempotency](retries.md) for what `max_retries`,
`retry_base_delay`, `retry_max_delay` do at runtime.
Expand Down Expand Up @@ -72,8 +76,9 @@ you also need other tuning.
- `ws_base_url` must be `wss://` for remote hosts; `ws://` is only allowed
against the same loopback set.
- Trailing slashes are auto-stripped from both.
- Unknown hosts log a warning (Kalshi's known hosts are
`api.elections.kalshi.com` and `demo-api.kalshi.co`).
- Unknown hosts are rejected by default; opt in via `allow_unknown_host`
(see the [Fields](#fields) table) or `KALSHI_ALLOW_UNKNOWN_HOST=1`. Kalshi's
known hosts are `api.elections.kalshi.com` and `demo-api.kalshi.co`.

This catches plaintext config slip-ups before any request is sent.

Expand Down
Loading