pykalshi 0.1.0__tar.gz

pykalshi-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/kalshi_api/__init__.py

@@ -0,0 +1,144 @@
+"""
+Kalshi API Client Library
+
+A clean, modular interface for the Kalshi trading API.
+"""
+
+import logging
+
+from .client import KalshiClient
+from .events import Event
+from .markets import Market, Series
+from .orders import Order
+from .portfolio import Portfolio
+from .exchange import Exchange
+from .api_keys import APIKeys
+from .feed import (
+    Feed,
+    TickerMessage,
+    OrderbookSnapshotMessage,
+    OrderbookDeltaMessage,
+    OrderbookMessage,
+    TradeMessage,
+    FillMessage,
+    PositionMessage,
+    MarketLifecycleMessage,
+    OrderGroupUpdateMessage,
+)
+from .enums import (
+    Side,
+    Action,
+    OrderType,
+    OrderStatus,
+    MarketStatus,
+    CandlestickPeriod,
+    TimeInForce,
+    SelfTradePrevention,
+)
+from .models import (
+    PositionModel,
+    FillModel,
+    OrderModel,
+    BalanceModel,
+    MarketModel,
+    EventModel,
+    OrderbookResponse,
+    CandlestickResponse,
+    ExchangeStatus,
+    Announcement,
+    APILimits,
+    APIKey,
+    GeneratedAPIKey,
+    SeriesModel,
+    TradeModel,
+    SettlementModel,
+    QueuePositionModel,
+    OrderGroupModel,
+    SubaccountModel,
+    SubaccountBalanceModel,
+    SubaccountTransferModel,
+    ForecastPercentileHistory,
+)
+from .orderbook import OrderbookManager
+from .rate_limiter import RateLimiter, NoOpRateLimiter
+from .exceptions import (
+    KalshiError,
+    KalshiAPIError,
+    AuthenticationError,
+    InsufficientFundsError,
+    ResourceNotFoundError,
+    RateLimitError,
+    OrderRejectedError,
+)
+
+# Set up logging to NullHandler by default to avoid "No handler found" warnings.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    # Client
+    "KalshiClient",
+    # Domain objects
+    "Event",
+    "Market",
+    "Series",
+    "Order",
+    "Portfolio",
+    "Exchange",
+    "APIKeys",
+    # Feed (WebSocket)
+    "Feed",
+    "TickerMessage",
+    "OrderbookSnapshotMessage",
+    "OrderbookDeltaMessage",
+    "OrderbookMessage",
+    "TradeMessage",
+    "FillMessage",
+    "PositionMessage",
+    "MarketLifecycleMessage",
+    "OrderGroupUpdateMessage",
+    # Enums
+    "Side",
+    "Action",
+    "OrderType",
+    "OrderStatus",
+    "MarketStatus",
+    "CandlestickPeriod",
+    "TimeInForce",
+    "SelfTradePrevention",
+    # Models
+    "PositionModel",
+    "FillModel",
+    "OrderModel",
+    "BalanceModel",
+    "MarketModel",
+    "EventModel",
+    "OrderbookResponse",
+    "CandlestickResponse",
+    "ExchangeStatus",
+    "Announcement",
+    "APILimits",
+    "APIKey",
+    "GeneratedAPIKey",
+    "SeriesModel",
+    "TradeModel",
+    "SettlementModel",
+    "QueuePositionModel",
+    "OrderGroupModel",
+    "ForecastPercentileHistory",
+    # Utilities
+    "OrderbookManager",
+    "RateLimiter",
+    "NoOpRateLimiter",
+    # Subaccount Models
+    "SubaccountModel",
+    "SubaccountBalanceModel",
+    "SubaccountTransferModel",
+    # Exceptions
+    "KalshiError",
+    "KalshiAPIError",
+    "AuthenticationError",
+    "InsufficientFundsError",
+    "ResourceNotFoundError",
+    "RateLimitError",
+    "OrderRejectedError",
+]

pykalshi-0.1.0/kalshi_api/api_keys.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from .models import APIKey, GeneratedAPIKey, APILimits
+
+if TYPE_CHECKING:
+    from .client import KalshiClient
+
+
+class APIKeys:
+    """API key management and account limits."""
+
+    def __init__(self, client: KalshiClient) -> None:
+        self._client = client
+
+    def list(self) -> list[APIKey]:
+        """List all API keys for this account."""
+        data = self._client.get("/api_keys")
+        return [APIKey.model_validate(k) for k in data.get("api_keys", [])]
+
+    def create(self, public_key: str, name: str | None = None) -> APIKey:
+        """Create an API key with a provided RSA public key.
+
+        Args:
+            public_key: PEM-encoded RSA public key.
+            name: Optional name for the key.
+        """
+        body: dict = {"public_key": public_key}
+        if name:
+            body["name"] = name
+        data = self._client.post("/api_keys", body)
+        return APIKey.model_validate(data["api_key"])
+
+    def generate(self, name: str | None = None) -> GeneratedAPIKey:
+        """Generate a new API key pair (Kalshi creates both keys).
+
+        Returns a GeneratedAPIKey with the private_key field populated.
+        The private key is only returned ONCE - store it securely.
+
+        Args:
+            name: Optional name for the key.
+        """
+        body: dict = {}
+        if name:
+            body["name"] = name
+        data = self._client.post("/api_keys/generate", body)
+        return GeneratedAPIKey.model_validate(data)
+
+    def delete(self, key_id: str) -> None:
+        """Delete an API key.
+
+        Args:
+            key_id: The API key ID to delete.
+        """
+        self._client.delete(f"/api_keys/{key_id}")
+
+    def get_limits(self) -> APILimits:
+        """Get API rate limits for this account."""
+        data = self._client.get("/account/limits")
+        return APILimits.model_validate(data)