Merge pull request #32 from pbeets/feat/batch6-api-updates

feat: align models with latest Kalshi API spec (batches 4-6)

Author: pbeets

CHANGELOG.md

@@ -119,6 +119,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- `TransferBetweenSubaccountsRequest` now exposes a `client_transfer_id()`
+  builder method. Previously the `client_transfer_id` field was hardcoded to an
+  empty string in the constructor with no way for users to set it.
 - `OrderbookAggregator` now drops delta messages that arrive before a snapshot
   instead of creating ghost orderbook entries. Previously, early deltas would
   insert empty uninitialized books into the state map, causing `full_book()` and

README.md

@@ -9,10 +9,12 @@ An unofficial Rust client library for the [Kalshi](https://kalshi.com) predictio
 
 ## Key Features
 
-This crate provides both REST API and WebSocket streaming capabilities:
-
-- **REST Client**: Full coverage of the Kalshi API including portfolio management, order operations, market data, exchange status, and RFQ (Request for Quote) communications
-- **WebSocket Streaming**: Real-time ticker, trade, orderbook, fill, and RFQ/quote updates with channel-based message delivery
+- **REST Client**: Full coverage of 84 Kalshi API endpoints including portfolio management, order operations, market data, exchange status, historical data, and RFQ (Request for Quote) communications
+- **WebSocket Streaming**: 10 real-time channels — ticker, trade, orderbook, fill, order updates, position, RFQ/quote, order groups, market lifecycle, and multivariate
+- **Batch Operations**: Rate-limited `BatchManager` with automatic chunking, retry, and per-order subaccount support
+- **Orderbook Aggregation**: Live orderbook state from WebSocket delta streams with gap detection
+- **Subaccount Support**: Full subaccount filtering on orders, fills, positions, settlements, and balance queries
+- **Fixed-Point Fields**: `_fp` and `_dollars` fields throughout for precise decimal arithmetic without floating-point issues
 
 ## Getting Started
 
@@ -142,21 +144,46 @@ let client = KalshiStreamClient::connect_with_strategy(&config, ConnectStrategy:
 
 ## Examples
 
-See the [`examples/`](examples/) directory for working examples:
+See the [`examples/`](examples/) directory for 24 working examples:
+
+### REST API
 
 | Example | Description |
 |---------|-------------|
-| `portfolio` | REST API: account balance, positions |
-| `trading` | REST API: order creation, amendment, cancellation |
-| `markets` | REST API: market data queries |
-| `stream_ticker` | WebSocket: real-time price updates |
-| `stream_user_channels` | WebSocket: fills, positions, RFQ communications |
+| `portfolio` | Account balance, positions, fills, settlements |
+| `trading` | Order lifecycle: create, amend, decrease, cancel |
+| `markets` | Market queries, orderbook, trades, pagination |
+| `events` | Events, series, metadata, multivariate, candlesticks, forecasts |
+| `candlesticks` | OHLCV data with multiple periods and batch queries |
+| `historical` | Archived data: cutoff, markets, candlesticks, fills, orders |
+| `batch_orders` | Batch create/cancel with partial success handling |
+| `batch_manager` | Rate-limited batch operations with `BatchManager` |
+| `order_groups` | Order group creation, management, triggering |
+| `exchange_status` | Exchange status, schedule, announcements, fee changes |
+| `live_data` | Live milestone data (single and batch) |
+| `milestones` | Milestone metadata queries |
+| `structured_targets` | Structured target lookups with type breakdown |
 | `rfq_verify` | RFQ system verification (read-only) |
-| `stream_reconnect` | WebSocket reconnection patterns |
+| `search` | Search filters by category and sport |
+| `series_and_search` | Series metadata and search combined |
+
+### WebSocket Streaming
+
+| Example | Description |
+|---------|-------------|
+| `stream_ticker` | Real-time ticker and trade updates |
+| `stream_user_channels` | Fills, positions, RFQ communications |
+| `stream_reconnect` | Reconnection with resubscription |
+| `stream_firehose` | High-volume streaming pattern |
+| `stream_lifecycle` | Market lifecycle events |
+| `multi_channel_subscribe` | Multi-channel subscription management |
+| `orderbook_aggregator` | Live orderbook state from delta streams |
+| `test_auth` | Basic authentication verification |
 
 ```bash
 cargo run --example portfolio
-cargo run --example rfq_verify
+cargo run --example trading
+cargo run --example historical
 ```
 
 ## Error Handling

examples/batch_orders.rs

@@ -184,16 +184,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             if let Some(order) = &result.order {
                 println!(
                     "  {} | CANCELED | reduced by: {} contracts",
-                    order.order_id,
-                    result.reduced_by.unwrap_or(0)
+                    order.order_id, result.reduced_by
                 );
                 canceled_count += 1;
             } else if let Some(error) = &result.error {
                 println!(
                     "  {} | FAILED | {}: {}",
-                    result.order_id.as_deref().unwrap_or("?"),
-                    error.code,
-                    error.message
+                    result.order_id, error.code, error.message
                 );
                 failed_count += 1;
             }

examples/candlesticks.rs

@@ -40,12 +40,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let market = markets
         .markets
         .iter()
-        .find(|m| m.volume.unwrap_or(0) > 0)
+        .find(|m| m.volume > 0)
         .unwrap_or(&markets.markets[0]);
 
     let ticker = &market.ticker;
     let series_ticker = &market.event_ticker;
-    let volume = market.volume.unwrap_or(0);
+    let volume = market.volume;
 
     println!("Selected market: {}", ticker);
     println!("Series: {}", series_ticker);
@@ -92,18 +92,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 .map(|dt| dt.format("%Y-%m-%d %H:%M").to_string())
                 .unwrap_or_else(|| candle.end_period_ts.to_string());
 
-            let (open, high, low, close) = if let Some(price) = &candle.price {
-                (
-                    price.open.map(|p| format!("${:.2}", cents_to_dollars(p))),
-                    price.high.map(|p| format!("${:.2}", cents_to_dollars(p))),
-                    price.low.map(|p| format!("${:.2}", cents_to_dollars(p))),
-                    price.close.map(|p| format!("${:.2}", cents_to_dollars(p))),
-                )
-            } else {
-                (None, None, None, None)
-            };
-
-            let volume = candle.volume.map(|v| v.to_string());
+            let price = &candle.price;
+            let open = price.open.map(|p| format!("${:.2}", cents_to_dollars(p)));
+            let high = price.high.map(|p| format!("${:.2}", cents_to_dollars(p)));
+            let low = price.low.map(|p| format!("${:.2}", cents_to_dollars(p)));
+            let close = price.close.map(|p| format!("${:.2}", cents_to_dollars(p)));
 
             println!(
                 "{:<20} {:>8} {:>8} {:>8} {:>8} {:>8}",
@@ -112,7 +105,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 high.as_deref().unwrap_or("-"),
                 low.as_deref().unwrap_or("-"),
                 close.as_deref().unwrap_or("-"),
-                volume.as_deref().unwrap_or("-")
+                candle.volume
             );
         }
 
@@ -142,23 +135,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 .map(|dt| dt.format("%H:%M:%S").to_string())
                 .unwrap_or_else(|| candle.end_period_ts.to_string());
 
-            let yes_bid = candle
-                .yes_bid
-                .as_ref()
-                .and_then(|b| b.close)
-                .map(|p| format!("${:.2}", cents_to_dollars(p)));
-            let yes_ask = candle
-                .yes_ask
-                .as_ref()
-                .and_then(|a| a.close)
-                .map(|p| format!("${:.2}", cents_to_dollars(p)));
+            let yes_bid = format!("${:.2}", cents_to_dollars(candle.yes_bid.close));
+            let yes_ask = format!("${:.2}", cents_to_dollars(candle.yes_ask.close));
 
-            println!(
-                "{:<20} {:>12} {:>12}",
-                timestamp,
-                yes_bid.as_deref().unwrap_or("-"),
-                yes_ask.as_deref().unwrap_or("-")
-            );
+            println!("{:<20} {:>12} {:>12}", timestamp, yes_bid, yes_ask);
         }
     }
     println!();
@@ -179,8 +159,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             .map(|dt| dt.format("%Y-%m-%d").to_string())
             .unwrap_or_else(|| candle.end_period_ts.to_string());
 
-        let vol = candle.volume.unwrap_or(0);
-        let oi = candle.open_interest.unwrap_or(0);
+        let vol = candle.volume;
+        let oi = candle.open_interest;
 
         println!("  {} | Volume: {} | Open Interest: {}", date, vol, oi);
     }

examples/events.rs

@@ -33,8 +33,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     println!("Total events returned: {}", events.events.len());
 
-    if let Some(cursor) = &events.cursor {
-        println!("Next cursor: {}...", &cursor[..cursor.len().min(20)]);
+    if !events.cursor.is_empty() {
+        println!(
+            "Next cursor: {}...",
+            &events.cursor[..events.cursor.len().min(20)]
+        );
     }
 
     println!();
@@ -47,12 +50,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     for event in &open_events.events {
         println!("  {} | {}", event.event_ticker, event.title);
-        if let Some(subtitle) = &event.sub_title {
-            println!("    Subtitle: {}", subtitle);
+        if !event.sub_title.is_empty() {
+            println!("    Subtitle: {}", event.sub_title);
         }
         println!("    Series: {}", event.series_ticker);
-        if let Some(category) = &event.category {
-            println!("    Category: {}", category);
+        if !event.category.is_empty() {
+            println!("    Category: {}", event.category);
         }
     }
     println!();
@@ -72,9 +75,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         if let Some(markets) = &event.markets {
             println!("  Markets ({}):", markets.len());
             for market in markets.iter().take(5) {
-                let title = market.title.as_deref().unwrap_or("(no title)");
-                let yes_ask = market.yes_ask_dollars.as_deref().unwrap_or("N/A");
-                println!("    {} | {} | YES ask: ${}", market.ticker, title, yes_ask);
+                println!(
+                    "    {} | {} | YES ask: ${}",
+                    market.ticker, market.title, market.yes_ask_dollars
+                );
             }
             if markets.len() > 5 {
                 println!("    ... and {} more markets", markets.len() - 5);
@@ -96,25 +100,23 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         println!("Ticker: {}", event.event_ticker);
         println!("Title: {}", event.title);
         println!("Series: {}", event.series_ticker);
-        if let Some(subtitle) = &event.sub_title {
-            println!("Subtitle: {}", subtitle);
-        }
-        if let Some(category) = &event.category {
-            println!("Category: {}", category);
+        if !event.sub_title.is_empty() {
+            println!("Subtitle: {}", event.sub_title);
         }
-        if let Some(mutually_exclusive) = event.mutually_exclusive {
-            println!("Mutually Exclusive: {}", mutually_exclusive);
+        if !event.category.is_empty() {
+            println!("Category: {}", event.category);
         }
+        println!("Mutually Exclusive: {}", event.mutually_exclusive);
         if let Some(strike_date) = &event.strike_date {
             println!("Strike Date: {}", strike_date);
         }
         if let Some(strike_period) = &event.strike_period {
             println!("Strike Period: {}", strike_period);
         }
 
-        // Check for markets in the deprecated field
-        if let Some(markets) = &event_response.markets {
-            println!("Markets (deprecated field): {}", markets.len());
+        // Check for markets in response
+        if !event_response.markets.is_empty() {
+            println!("Markets: {}", event_response.markets.len());
         }
         println!();
 
@@ -131,20 +133,16 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             );
             for market in markets {
                 let status = format!("{:?}", market.status);
-                let volume = market.volume.unwrap_or(0);
-                let oi = market.open_interest.unwrap_or(0);
-
                 println!(
                     "  {} | {} | vol: {} | oi: {}",
-                    market.ticker, status, volume, oi
+                    market.ticker, status, market.volume, market.open_interest
                 );
 
-                // Show pricing if available
-                if let (Some(yes_bid), Some(yes_ask)) =
-                    (&market.yes_bid_dollars, &market.yes_ask_dollars)
-                {
-                    println!("    YES: ${} bid / ${} ask", yes_bid, yes_ask);
-                }
+                // Show pricing
+                println!(
+                    "    YES: ${} bid / ${} ask",
+                    market.yes_bid_dollars, market.yes_ask_dollars
+                );
             }
         }
         println!();
@@ -211,9 +209,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
         println!("Page {}: fetched {} events", page, fetched);
 
-        if let Some(next_cursor) = response.cursor {
+        if !response.cursor.is_empty() {
             if page < MAX_PAGES {
-                cursor = Some(next_cursor);
+                cursor = Some(response.cursor);
             } else {
                 println!("Stopping after {} pages (demo limit)", MAX_PAGES);
                 break;
@@ -298,8 +296,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 market_candles.len()
             );
         }
-        if let Some(adjusted) = candles.adjusted_end_ts {
-            println!("Adjusted end timestamp: {}", adjusted);
+        if candles.adjusted_end_ts != 0 {
+            println!("Adjusted end timestamp: {}", candles.adjusted_end_ts);
         }
         println!();
 
@@ -336,13 +334,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                         point.event_ticker, point.end_period_ts, point.period_interval
                     );
                     for pp in &point.percentile_points {
-                        let formatted = pp.formatted_forecast.as_deref().unwrap_or("-");
-                        let numerical = pp.numerical_forecast.map(|v| format!("{:.2}", v));
                         println!(
-                            "    {}th percentile: {} ({})",
+                            "    {}th percentile: {} ({:.2})",
                             pp.percentile / 100,
-                            formatted,
-                            numerical.as_deref().unwrap_or("-")
+                            pp.formatted_forecast,
+                            pp.numerical_forecast
                         );
                     }
                 }

examples/exchange_status.rs

@@ -63,12 +63,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Display each day's schedule from the first (current) period
     if let Some(period) = schedule.standard_hours.first() {
-        if let Some(start) = &period.start_time {
-            println!("Effective from: {}", start);
-        }
-        if let Some(end) = &period.end_time {
-            println!("Until: {}", end);
-        }
+        println!("Effective from: {}", period.start_time);
+        println!("Until: {}", period.end_time);
         println!();
 
         print_day_sessions("Monday   ", &period.monday);

examples/historical.rs

@@ -36,15 +36,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     for market in &markets.markets {
         println!(
             "  {} | {:?} | result: {:?} | vol: {}",
-            market.ticker,
-            market.status,
-            market.result,
-            market.volume.unwrap_or(0)
+            market.ticker, market.status, market.result, market.volume
         );
     }
 
-    if let Some(cursor) = &markets.cursor {
-        println!("  Next cursor: {}...", &cursor[..cursor.len().min(20)]);
+    if !markets.cursor.is_empty() {
+        println!(
+            "  Next cursor: {}...",
+            &markets.cursor[..markets.cursor.len().min(20)]
+        );
     }
     println!();
 
@@ -56,7 +56,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         let detail = client.get_historical_market(ticker).await?;
         let m = &detail.market;
 
-        println!("  Title: {}", m.title.as_deref().unwrap_or("(none)"));
+        println!("  Title: {}", m.title);
         println!("  Event: {}", m.event_ticker);
         println!("  Type: {:?}", m.market_type);
         println!("  Status: {:?}", m.status);
@@ -79,11 +79,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             Ok(candles) => {
                 println!("  {} candlesticks returned", candles.candlesticks.len());
                 for candle in candles.candlesticks.iter().take(3) {
-                    let close = candle
-                        .price
-                        .as_ref()
-                        .and_then(|p| p.close.as_deref())
-                        .unwrap_or("N/A");
+                    let close = candle.price.close.as_deref().unwrap_or("N/A");
                     println!(
                         "    ts={} close=${} vol={}",
                         candle.end_period_ts, close, candle.volume