From 01ee28656e1b9fa003e84abc7741c5d19904ff88 Mon Sep 17 00:00:00 2001 From: Jeff West Date: Fri, 10 Jul 2026 09:24:34 -0500 Subject: [PATCH] docs: fix strict build + update all docs for v7.0.0 accuracy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes the failing `mkdocs build --strict` Docs workflow (pre-existing, broken since the v6.0.0 merge) and brings the docs current for v7.0.0. Build fix (docs/migration.md): - `../CHANGELOG.md` → absolute GitHub URL (the cross-tree link failed strict mode). - Broken `#v5--v600` anchor → `#v5-v600`. v7.0.0 accuracy: - New "v6 → v7.0.0" migration section (price_cents→price, announcements soft-deprecation, the 3 new endpoints, exchange_index/asset_class additions). - subaccounts: transfer_position `price_cents` → `price` (Decimal dollars) in the quick-ref table, prose, and example; netting example fixed to use `netting_configs` (+ `exchange_index`); dropped a stale field reference. - exchange: announcements deprecation admonition; corrected the example to the real model fields (`type`/`message`/`delivery_time`/`status`, not `title`). - pagination: note announcements is deprecated/404s. - portfolio: `balance(*, exchange_index=...)` param. - perps: note the two new klear margin methods. - OpenAPI version bumped 3.23.0 → 3.24.0 in README, docs/index.md, CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 2 +- README.md | 2 +- docs/index.md | 2 +- docs/migration.md | 71 ++++++++++++++++++++++++++++++++++- docs/pagination.md | 3 +- docs/perps.md | 5 +++ docs/resources/exchange.md | 13 +++++-- docs/resources/portfolio.md | 5 ++- docs/resources/subaccounts.md | 18 +++++---- 9 files changed, 103 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 410e6003..b03a95b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -122,7 +122,7 @@ tests/ ## API Reference -- OpenAPI spec: https://docs.kalshi.com/openapi.yaml (v3.23.0, 101 operations) +- OpenAPI spec: https://docs.kalshi.com/openapi.yaml (v3.24.0, 101 operations) - AsyncAPI spec: https://docs.kalshi.com/asyncapi.yaml (13 WebSocket channels) - Base URL: https://api.elections.kalshi.com/trade-api/v2 - Demo URL: https://demo-api.kalshi.co/trade-api/v2 diff --git a/README.md b/README.md index 8a6e129e..eb48b53f 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ A professional, spec-first Python SDK for the [Kalshi](https://kalshi.com) predi [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Type checked: mypy strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy.readthedocs.io/) -- **Full coverage** of the Kalshi REST API (101 operations across 19 resources, OpenAPI v3.23.0) and WebSocket API (12 typed `subscribe_*` channels + 2 escape-hatch). +- **Full coverage** of the Kalshi REST API (101 operations across 19 resources, OpenAPI v3.24.0) and WebSocket API (12 typed `subscribe_*` channels + 2 escape-hatch). - **Perps (margin) API**: standalone `PerpsClient` / `AsyncPerpsClient` + `PerpsWebSocket` for the perpetual-futures exchange (34 REST operations, 6 WS channels), plus a `KlearClient` for the Self-Clearing-Member "Klear" settlement API (9 operations). See [Perps (margin) trading](#perps-margin-trading). - **FIX protocol**: an async-first FIX engine (FIXT.1.1 / FIX50SP2) for both products — order-entry, drop-copy, market-data, post-trade (prediction), and RFQ (prediction) sessions (plus order-group management over the order-entry session) with typed message models, sequence recovery, and order-book / settlement reassembly. `from kalshi import FixClient` / `MarginFixClient`. See [FIX protocol](#fix-protocol-low-latency-trading). - **V2 event-market orders**: `create_v2` / `amend_v2` / `decrease_v2` / `cancel_v2` plus batched variants on `/portfolio/events/orders/*` — the only order-write surface. diff --git a/docs/index.md b/docs/index.md index 3365a8d3..c1a1708c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@ A professional, spec-first Python SDK for the [Kalshi](https://kalshi.com) prediction markets API. -- **Full REST coverage** — 101 operations across 19 resources (OpenAPI v3.23.0), +- **Full REST coverage** — 101 operations across 19 resources (OpenAPI v3.24.0), every kwarg drift-tested against the spec. - **V2 event-market orders** — new `create_v2` / `amend_v2` / `decrease_v2` / `cancel_v2` family on `/portfolio/events/orders/*`. Legacy `/portfolio/orders` diff --git a/docs/migration.md b/docs/migration.md index 924fbfa2..6579e7a4 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,5 +1,71 @@ # Migration +## v6 → v7.0.0 + +Syncs the SDK to OpenAPI/AsyncAPI spec **3.24.0**. One breaking change on the +subaccounts surface, one soft-deprecation, three new endpoints, and additive +field/param additions. + +### Breaking: position-transfer price is fixed-point dollars, not integer cents + +The per-contract price on `subaccounts.transfer_position()` (and the underlying +`ApplySubaccountPositionTransferRequest` / `SubaccountTransfer` models) is renamed +from **`price_cents`** (integer cents, 0–100) to **`price`** (`Decimal`, +fixed-point dollars, 0–1.0). Upstream renamed the wire field `price_cents` → +`price` (`FixedPointDollars`) in 3.24.0. + +```python +from decimal import Decimal + +# v6 (removed) +# client.subaccounts.transfer_position( +# client_transfer_id=..., from_subaccount=0, to_subaccount=1, +# market_ticker="MKT-A", side="yes", count=5, price_cents=55, +# ) + +# v7 — price is dollars, as a Decimal +client.subaccounts.transfer_position( + client_transfer_id=..., + from_subaccount=0, + to_subaccount=1, + market_ticker="MKT-A", + side="yes", + count=5, + price=Decimal("0.55"), # 55¢ cost basis +) +``` + +The old client-side `0–100` cap is gone. `price` uses `OrderPrice`, which guards +non-negativity and the `$0.0001` tick (matching `CreateOrderRequest`); the upper +bound is the server's to enforce. + +### Deprecated: `exchange.announcements()` + +Kalshi removed `GET /exchange/announcements` and the `Announcement` schema from +the spec in 3.24.0, so the live endpoint now 404s. `exchange.announcements()` +(sync + async) and the `Announcement` model are **retained** but emit a +`DeprecationWarning` — upstream has transiently dropped endpoints as publishing +glitches before, so the method is kept pending confirmation the removal is +permanent. A future major release removes them. + +### Added + +- **`communications.quotes.get_for_rfq(rfq_id, quote_id)`** (sync + async) — + `GET /communications/rfqs/{rfq_id}/quotes/{quote_id}`, the RFQ-scoped get-quote + (returns `GetQuoteResponse`, the same payload as the flat `quotes.get`). +- **`klear.margin.active_obligations()`** (sync + async) — + `GET /margin/active_obligations`, all currently-active settlement obligations. +- **`klear.margin.settlement_estimate_by_asset_class()`** (sync + async) — + `GET /margin/settlement_estimate_by_asset_class`, next-settlement estimates + keyed by asset class. +- **`SubaccountNettingConfig.exchange_index`** (`int`, required). +- **`portfolio.balance(*, exchange_index=...)`** — optional query param to target + a specific exchange shard (defaults to 0 server-side). +- **`ObligationEntry.asset_class`** (perps SCM / Klear; `Literal["Crypto"]`). + +See the [changelog](https://github.com/TexasCoding/kalshi-python-sdk/blob/main/CHANGELOG.md) +for the full list. + ## v5 → v6.0.0 **Breaking: multivariate lookup-history is gone.** Kalshi removed the @@ -24,7 +90,8 @@ Everything else in 6.0.0 is additive and needs no code changes: subaccounts. - `subaccounts.create()` gained an optional `exchange_index` argument. -See the [changelog](../CHANGELOG.md) for the full list. +See the [changelog](https://github.com/TexasCoding/kalshi-python-sdk/blob/main/CHANGELOG.md) +for the full list. ## v4 → v5.0.0 @@ -435,7 +502,7 @@ instead. The endpoints still work; calls just emit a `DeprecationWarning` on first use. (`multivariate.lookup_history`, also deprecated here in #269, was removed -entirely in 6.0.0 — see the [v5 → v6.0.0](#v5--v600) section above.) +entirely in 6.0.0 — see the [v5 → v6.0.0](#v5-v600) section above.) ### `orders.list(event_ticker=...)` accepts lists diff --git a/docs/pagination.md b/docs/pagination.md index 58764c16..8790826c 100644 --- a/docs/pagination.md +++ b/docs/pagination.md @@ -68,7 +68,8 @@ There is **no** built-in 1000-page cap. If you want one, pass A few list endpoints return a plain `list[T]`, not `Page[T]`: - `client.series.list(...)` — flat list of series. -- `client.exchange.announcements()` — a flat list. +- `client.exchange.announcements()` — a flat list (deprecated in v7.0.0; the + endpoint was removed upstream and now 404s). - `client.order_groups.list()` — no cursor. - `client.account.limits()` / `client.exchange.status()` — single objects. - `client.markets.bulk_orderbooks(...)` / `bulk_candlesticks(...)` — flat list of up to 100 items. diff --git a/docs/perps.md b/docs/perps.md index 5cca4254..adc978ec 100644 --- a/docs/perps.md +++ b/docs/perps.md @@ -179,6 +179,11 @@ with KlearClient(admin_user_id="...", access_token="...", demo=True) as klear: Credentials can also come from the environment via `KlearClient.from_env()` (reads `KALSHI_KLEAR_ADMIN_USER_ID` / `KALSHI_KLEAR_ACCESS_TOKEN`). +New in spec v3.24.0: `klear.margin.active_obligations()` returns all +currently-active settlement obligations (the plural sibling of the single-obligation +`active_obligation()`), and `klear.margin.settlement_estimate_by_asset_class()` +returns next-settlement estimates keyed by asset class. + Money fields on the Klear margin schemas are integer **centicents** (`1 USD = 10,000 centicents`); only the withdrawal `amount` is a fixed-point dollar string. `klear.margin.withdraw_settlement_balance(amount="500.00")` validates the amount as diff --git a/docs/resources/exchange.md b/docs/resources/exchange.md index 7c686eba..0b4ac6f4 100644 --- a/docs/resources/exchange.md +++ b/docs/resources/exchange.md @@ -9,7 +9,7 @@ Top-level exchange status, schedule, announcements, and your account's |---|---|---| | `status()` | `GET /exchange/status` | no | | `schedule()` | `GET /exchange/schedule` | no | -| `announcements()` | `GET /exchange/announcements` | no | +| `announcements()` *(deprecated in v7.0.0 — 404s)* | `GET /exchange/announcements` | no | | `user_data_timestamp()` | `GET /exchange/user_data_timestamp` | **yes** | ## Exchange status @@ -36,9 +36,16 @@ for window in sched.maintenance_windows: ## Announcements +!!! warning "Deprecated in v7.0.0" + Kalshi removed `GET /exchange/announcements` and the `Announcement` schema + from the spec in 3.24.0, so the live endpoint now **404s**. `announcements()` + (sync + async) and the `Announcement` model are retained — each call emits a + `DeprecationWarning` — pending confirmation the removal is permanent, and will + be removed in a future major release. + ```python -for a in client.exchange.announcements(): - print(a.title, a.message, a.delivery_time) +for a in client.exchange.announcements(): # emits DeprecationWarning + print(a.type, a.message, a.delivery_time, a.status) ``` Plain list, not a `Page`. diff --git a/docs/resources/portfolio.md b/docs/resources/portfolio.md index eca70bf2..30eeaa47 100644 --- a/docs/resources/portfolio.md +++ b/docs/resources/portfolio.md @@ -7,7 +7,7 @@ Auth required throughout. | Method | Endpoint | |---|---| -| `balance(*, subaccount=None)` | `GET /portfolio/balance` | +| `balance(*, subaccount=None, exchange_index=None)` | `GET /portfolio/balance` | | `positions(*, ...)` | `GET /portfolio/positions` | | `settlements(...)` / `settlements_all(...)` | `GET /portfolio/settlements` | | `fills(...)` / `fills_all(...)` | `GET /portfolio/fills` | @@ -18,7 +18,8 @@ Auth required throughout. `balance()`, `positions()` / `positions_all()`, `settlements()` / `settlements_all()`, and `fills()` / `fills_all()` all take an optional `subaccount: int` to scope the read to a specific subaccount (omit for the -primary account). +primary account). `balance()` also takes an optional `exchange_index: int` +(spec v3.24.0) to target a specific exchange shard (defaults to 0 server-side). ## Balance diff --git a/docs/resources/subaccounts.md b/docs/resources/subaccounts.md index 0606c701..445037ea 100644 --- a/docs/resources/subaccounts.md +++ b/docs/resources/subaccounts.md @@ -9,7 +9,7 @@ primary; `1`–`63` are numbered extras. Auth required throughout. |---|---| | `create(*, exchange_index=None)` | `POST /portfolio/subaccounts` | | `transfer(*, client_transfer_id, from_subaccount, to_subaccount, amount_cents)` | `POST /portfolio/subaccounts/transfer` | -| `transfer_position(*, client_transfer_id, from_subaccount, to_subaccount, market_ticker, side, count, price_cents)` | `POST /portfolio/subaccounts/positions/transfer` | +| `transfer_position(*, client_transfer_id, from_subaccount, to_subaccount, market_ticker, side, count, price)` | `POST /portfolio/subaccounts/positions/transfer` | | `list_balances()` | `GET /portfolio/subaccounts/balances` | | `list_transfers(*, cursor=None, limit=None)` | `GET /portfolio/subaccounts/transfers` | | `list_all_transfers(*, limit=None, max_pages=None)` | walks `list_transfers` | @@ -53,11 +53,13 @@ with the same id; the server dedupes. ## Transfer a position between subaccounts Spec v3.23.0 added `transfer_position()` for moving open contracts (not cash) -between subaccounts. Unlike `transfer()`, it returns a -`position_transfer_id`. `price_cents` (0–100) sets the cost basis on the -destination: +between subaccounts. Unlike `transfer()`, it returns a `position_transfer_id`. +`price` (spec v3.24.0 renamed it from `price_cents`) is the per-contract cost +basis in **fixed-point dollars** (0–1.0) — pass a `Decimal`: ```python +from decimal import Decimal + resp = client.subaccounts.transfer_position( client_transfer_id=uuid.uuid4(), # or str from_subaccount=0, @@ -65,7 +67,7 @@ resp = client.subaccounts.transfer_position( market_ticker="KXBTC-25DEC31-B100000", side="yes", # "yes" | "no" count=10, # contracts (> 0) - price_cents=55, # per-contract cents, 0–100 + price=Decimal("0.55"), # per-contract dollars, 0–1.0 ) print(resp.position_transfer_id) ``` @@ -101,8 +103,10 @@ Netting offsets positions across subaccounts so they consume one margin pool. ```python client.subaccounts.update_netting(subaccount_number=1, enabled=True) -config = client.subaccounts.get_netting() -print(config.netting_enabled_subaccounts) +resp = client.subaccounts.get_netting() +for cfg in resp.netting_configs: + # `exchange_index` (int) added in spec v3.24.0. + print(cfg.subaccount_number, cfg.enabled, cfg.exchange_index) ``` ## Reference