pykalshi 0.1.0__py3-none-any.whl

kalshi_api/rate_limiter.py

@@ -0,0 +1,171 @@
+"""
+Rate limiter for proactive request throttling.
+
+Composable, optional, and easy to remove. Inject into KalshiClient
+to prevent 429s rather than just retrying after them.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+class RateLimiterProtocol(Protocol):
+    """Protocol for rate limiters. Implement this to create custom limiters."""
+
+    def acquire(self, weight: int = 1) -> float:
+        """Acquire permission to make a request.
+
+        Args:
+            weight: Cost of this request (default 1).
+
+        Returns:
+            Time waited in seconds (0 if no wait).
+        """
+        ...
+
+    def update_from_headers(self, remaining: int | None, reset_at: int | None) -> None:
+        """Update internal state from response headers.
+
+        Args:
+            remaining: Requests remaining in current window.
+            reset_at: Unix timestamp when window resets.
+        """
+        ...
+
+
+@dataclass
+class RateLimiter:
+    """Token bucket rate limiter with sliding window.
+
+    Thread-safe. Proactively throttles requests to stay under limits.
+
+    Usage:
+        limiter = RateLimiter(requests_per_second=10)
+        client = KalshiClient(..., rate_limiter=limiter)
+
+        # Or manual usage:
+        limiter.acquire()  # Blocks if needed
+        response = make_request()
+        limiter.update_from_headers(
+            remaining=int(response.headers.get('X-RateLimit-Remaining')),
+            reset_at=int(response.headers.get('X-RateLimit-Reset')),
+        )
+
+    Attributes:
+        requests_per_second: Target request rate.
+        burst: Maximum burst size (default: 2x requests_per_second).
+        min_spacing_ms: Minimum ms between requests (anti-burst).
+    """
+
+    requests_per_second: float = 10.0
+    burst: int | None = None
+    min_spacing_ms: float = 0.0
+
+    _timestamps: deque = field(default_factory=deque, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+    _last_request: float = field(default=0.0, repr=False)
+
+    # Server-reported state (updated from headers)
+    _server_remaining: int | None = field(default=None, repr=False)
+    _server_reset_at: int | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.burst is None:
+            self.burst = max(1, int(self.requests_per_second * 2))
+        self._window_size = 1.0  # 1 second sliding window
+
+    def acquire(self, weight: int = 1) -> float:
+        """Block until request is allowed. Returns wait time in seconds."""
+        with self._lock:
+            now = time.monotonic()
+            waited = 0.0
+
+            # Enforce minimum spacing
+            if self.min_spacing_ms > 0:
+                elapsed = (now - self._last_request) * 1000
+                if elapsed < self.min_spacing_ms:
+                    sleep_time = (self.min_spacing_ms - elapsed) / 1000
+                    time.sleep(sleep_time)
+                    waited += sleep_time
+                    now = time.monotonic()
+
+            # Clean old timestamps outside window
+            cutoff = now - self._window_size
+            while self._timestamps and self._timestamps[0] < cutoff:
+                self._timestamps.popleft()
+
+            # If at capacity, wait for oldest to expire
+            while len(self._timestamps) >= self.requests_per_second:
+                oldest = self._timestamps[0]
+                sleep_time = oldest + self._window_size - now
+                if sleep_time > 0:
+                    time.sleep(sleep_time)
+                    waited += sleep_time
+                    now = time.monotonic()
+                # Re-clean after sleep
+                cutoff = now - self._window_size
+                while self._timestamps and self._timestamps[0] < cutoff:
+                    self._timestamps.popleft()
+
+            # Check server-reported limits (be conservative)
+            if self._server_remaining is not None and self._server_remaining <= 1:
+                if self._server_reset_at is not None:
+                    sleep_until = self._server_reset_at - time.time()
+                    if sleep_until > 0:
+                        time.sleep(sleep_until)
+                        waited += sleep_until
+                        now = time.monotonic()
+                        self._server_remaining = None
+
+            # Record this request
+            for _ in range(weight):
+                self._timestamps.append(now)
+            self._last_request = now
+
+            return waited
+
+    def update_from_headers(
+        self, remaining: int | None, reset_at: int | None
+    ) -> None:
+        """Update state from X-RateLimit-Remaining and X-RateLimit-Reset headers."""
+        with self._lock:
+            if remaining is not None:
+                self._server_remaining = remaining
+            if reset_at is not None:
+                self._server_reset_at = reset_at
+
+    @property
+    def current_rate(self) -> float:
+        """Current request rate (requests in last second)."""
+        with self._lock:
+            now = time.monotonic()
+            cutoff = now - self._window_size
+            while self._timestamps and self._timestamps[0] < cutoff:
+                self._timestamps.popleft()
+            return len(self._timestamps)
+
+    def reset(self) -> None:
+        """Clear all state. Useful for testing."""
+        with self._lock:
+            self._timestamps.clear()
+            self._last_request = 0.0
+            self._server_remaining = None
+            self._server_reset_at = None
+
+
+@dataclass
+class NoOpRateLimiter:
+    """Rate limiter that does nothing. For testing or opt-out."""
+
+    def acquire(self, weight: int = 1) -> float:
+        return 0.0
+
+    def update_from_headers(
+        self, remaining: int | None, reset_at: int | None
+    ) -> None:
+        pass

pykalshi-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pykalshi
+Version: 0.1.0
+Summary: A typed Python client for the Kalshi prediction markets API with WebSocket streaming, automatic retries, and ergonomic interfaces
+Author-email: Arsh Koneru <arshkon@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ArshKA/kalshi-api
+Project-URL: Repository, https://github.com/ArshKA/kalshi-api
+Project-URL: Documentation, https://github.com/ArshKA/kalshi-api#readme
+Project-URL: Issues, https://github.com/ArshKA/kalshi-api/issues
+Keywords: kalshi,prediction-markets,trading,api-client,websocket,finance,betting,forecasting,elections,event-contracts,binary-options,real-time,async,pydantic,orderbook,market-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: websockets>=11.0
+Provides-Extra: web
+Requires-Dist: fastapi>=0.100.0; extra == "web"
+Requires-Dist: uvicorn>=0.23.0; extra == "web"
+Requires-Dist: aiofiles>=23.0.0; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+# kalshi-api
+
+A typed Python client for the [Kalshi](https://kalshi.com) prediction markets API with WebSocket streaming, automatic retries, and ergonomic interfaces.
+
+## Installation
+
+```bash
+pip install kalshi-api
+```
+
+Create a `.env` file with your credentials from [kalshi.com](https://kalshi.com) → Account & Security → API Keys:
+
+```
+KALSHI_API_KEY_ID=your-key-id
+KALSHI_PRIVATE_KEY_PATH=/path/to/private-key.key
+```
+
+## Quick Start
+
+```python
+from kalshi_api import KalshiClient, Action, Side
+
+client = KalshiClient()
+user = client.get_user()
+
+# Browse markets
+markets = client.get_markets(status="open", limit=5)
+market = client.get_market("KXBTC-25JAN15-B100000")
+
+# Place an order
+order = user.place_order(
+    market,
+    action=Action.BUY,
+    side=Side.YES,
+    count=10,
+    price=45  # cents
+)
+
+order.cancel()  # if needed
+```
+
+## Usage
+
+### Portfolio
+
+`KalshiClient` handles authentication. Call `get_user()` to access your portfolio:
+
+```python
+client = KalshiClient()              # Uses .env credentials
+client = KalshiClient(demo=True)     # Use demo environment
+
+user = client.get_user()
+user.get_balance()                   # BalanceModel with balance, portfolio_value
+user.get_positions()                 # Your current positions
+user.get_fills()                     # Your trade history
+user.get_orders(status="resting")    # Your open orders
+```
+
+### Markets
+
+```python
+# Search markets
+markets = client.get_markets(series_ticker="KXBTC", status="open")
+
+# Get a specific market
+market = client.get_market("KXBTC-25JAN15-B100000")
+print(market.title, market.yes_bid, market.yes_ask)
+
+# Market data
+orderbook = market.get_orderbook()
+trades = market.get_trades()
+```
+
+### Orders
+
+```python
+from kalshi_api import Action, Side, OrderType
+
+# Limit order (default)
+order = user.place_order(market, Action.BUY, Side.YES, count=10, price=50)
+
+# Market order
+order = user.place_order(market, Action.BUY, Side.YES, count=10, order_type=OrderType.MARKET)
+
+order.cancel()
+```
+
+### Real-time Streaming
+
+Subscribe to live market data via WebSocket:
+
+```python
+from kalshi_api import Feed
+
+async def main():
+    async with Feed(client) as feed:
+        await feed.subscribe_ticker("KXBTC-25JAN15-B100000")
+        await feed.subscribe_orderbook("KXBTC-25JAN15-B100000")
+
+        async for msg in feed:
+            print(msg)  # TickerMessage, OrderbookSnapshotMessage, etc.
+```
+
+### Error Handling
+
+```python
+from kalshi_api import InsufficientFundsError, RateLimitError, KalshiAPIError
+
+try:
+    user.place_order(...)
+except InsufficientFundsError:
+    print("Not enough balance")
+except RateLimitError:
+    pass  # Client auto-retries with backoff
+except KalshiAPIError as e:
+    print(f"{e.status_code}: {e.error_code}")
+```
+
+## Comparison with Official SDK
+
+| Feature | kalshi-api | kalshi-python (official) |
+|---------|------------|--------------------------|
+| WebSocket streaming | ✓ | — |
+| Automatic retry with backoff | ✓ | — |
+| Rate limit handling | ✓ | — |
+| Domain objects (`Market`, `Order`) | ✓ | — |
+| Typed exceptions | ✓ | — |
+| Local orderbook management | ✓ | — |
+| Pydantic models | ✓ | — |
+| Core trading API coverage | ✓ | ✓ |
+| Full API coverage | — | ✓ |
+
+The official SDK is auto-generated from the OpenAPI spec. This library adds the infrastructure needed for production trading: real-time data, error recovery, and ergonomic interfaces.
+
+## Links
+
+- [Kalshi API Reference](https://trading-api.readme.io/reference)
+- [kalshi-python (official SDK)](https://github.com/Kalshi/kalshi-python)

pykalshi-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+kalshi_api/__init__.py,sha256=H873JDfBga0KEi-G-EJOPBljMZiOTOcpw7x2Qaeru9w,3018
+kalshi_api/api_keys.py,sha256=HMn5bzKo5yX8edcKpJy20NbrR2z7vUa5PJk8TB0iBwU,1922
+kalshi_api/client.py,sha256=4IA-f8OSMFYvxf8tmKL06-2gb7GdDISHDLUPdCtF9ac,19362
+kalshi_api/enums.py,sha256=9YF4ooA1RTprI08-NzqVZoPXISAmHDWgv3j0971BRyI,1127
+kalshi_api/events.py,sha256=0eC9xlqBblwxJdmdiFwjuiL1XUbw6eqcK-vCjoUUgqA,2683
+kalshi_api/exceptions.py,sha256=ikv97ztZwYWKr4SZ0EUTtR50KZQFjbpuI5vMMpPxiW4,3143
+kalshi_api/exchange.py,sha256=39-Zx-VZ6ezkOeB4E9fP4yhTX-qoO4FRSkpcEGmhG60,1359
+kalshi_api/feed.py,sha256=zhPGaER7oBMAHZgpxdppvWDkC-NLn6W_ORnLCkCQh_8,19470
+kalshi_api/markets.py,sha256=ben3yUqpW2Jn1bp67lJ7gyRjUHtwPTZkKQxyH_ao3ZA,6901
+kalshi_api/models.py,sha256=hQdkJMK4sFYXiDEjjEwsEY4skBXEzN3IuJFpzojF8Lw,16038
+kalshi_api/orderbook.py,sha256=40UIqEz-pgM49YdFNTXAd63Rw2hCaEq-sQPPy9l3q_E,4830
+kalshi_api/orders.py,sha256=F4mk0PPS_cBzDRbg0x50GpQb-AqfJPES2Vw45Zes3Rc,3726
+kalshi_api/portfolio.py,sha256=JgkgGTSEytn3OrIRbdci-bvkBOtRmxBK69uFuyYwArI,19937
+kalshi_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kalshi_api/rate_limiter.py,sha256=UJPjl-YUtLdVwQcaoq97ZH1oeS-IhqtV8K5G6WpUyDg,5901
+pykalshi-0.1.0.dist-info/licenses/LICENSE,sha256=dUhuoK-TCRQMpuLEAdfme-qPSJI0TlcH9jlNxeg9_EQ,1056
+pykalshi-0.1.0.dist-info/METADATA,sha256=qYNSSrd3cUElCZt-FuL0MoSifw7NdKoQlx6lpjcfYRo,5603
+pykalshi-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pykalshi-0.1.0.dist-info/top_level.txt,sha256=j1cmqf7vUVoke4KfEg_he913wTsgN5nT0Ky5P3P7Dik,11
+pykalshi-0.1.0.dist-info/RECORD,,

pykalshi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pykalshi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pykalshi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kalshi_api