problee 0.1.0__py3-none-any.whl

problee/__init__.py

@@ -0,0 +1,35 @@
+"""
+Problee Python SDK
+
+Official Python client for the Problee prediction market API.
+"""
+
+__version__ = "0.1.0"
+
+from .client import ProbClient
+from .models.market import Market, MarketStatus, MarketCategory
+from .models.position import Position
+from .models.quote import Quote
+from .exceptions import (
+    ProbError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    APIError,
+)
+
+__all__ = [
+    "ProbClient",
+    "Market",
+    "MarketStatus",
+    "MarketCategory",
+    "Position",
+    "Quote",
+    "ProbError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "APIError",
+]

problee/api/__init__.py

@@ -0,0 +1,13 @@
+"""
+Problee API Modules
+"""
+
+from .markets import MarketsAPI
+from .positions import PositionsAPI
+from .quotes import QuotesAPI
+
+__all__ = [
+    "MarketsAPI",
+    "PositionsAPI",
+    "QuotesAPI",
+]

problee/api/markets.py

@@ -0,0 +1,119 @@
+"""
+Markets API
+"""
+
+from typing import Optional, List, TYPE_CHECKING
+from ..models.market import Market, MarketListResponse, MarketStatus, MarketCategory
+
+if TYPE_CHECKING:
+    from ..client import ProbClient
+
+
+class MarketsAPI:
+    """Markets API methods."""
+
+    def __init__(self, client: "ProbClient"):
+        self._client = client
+
+    def list(
+        self,
+        status: Optional[str] = None,
+        category: Optional[str] = None,
+        sort: Optional[str] = None,
+        limit: int = 20,
+        cursor: Optional[str] = None,
+    ) -> MarketListResponse:
+        """
+        List markets with optional filters.
+
+        Args:
+            status: Filter by status (open, closed, resolved)
+            category: Filter by category (sports, politics, crypto, entertainment, other)
+            sort: Sort order (new, trending, volume_24h, closing_soon)
+            limit: Max results per page (default 20, max 100)
+            cursor: Pagination cursor
+
+        Returns:
+            MarketListResponse with list of markets and pagination info
+        """
+        params = {"limit": limit}
+        if status:
+            params["status"] = status
+        if category:
+            params["category"] = category
+        if sort:
+            params["sort"] = sort
+        if cursor:
+            params["cursor"] = cursor
+
+        response = self._client._request("GET", "/api/v1/markets", params=params)
+        return MarketListResponse.from_dict(response)
+
+    def get(self, market_id: str) -> Market:
+        """
+        Get a single market by ID (address).
+
+        Args:
+            market_id: Market address
+
+        Returns:
+            Market object
+        """
+        response = self._client._request("GET", f"/api/v1/markets/{market_id}")
+        return Market.from_dict(response)
+
+    def get_history(
+        self,
+        market_id: str,
+        interval: str = "1h",
+        limit: int = 100,
+    ) -> List[dict]:
+        """
+        Get price history for a market.
+
+        Args:
+            market_id: Market address
+            interval: Time bucket (1m, 5m, 1h, 1d)
+            limit: Max data points
+
+        Returns:
+            List of price history points
+        """
+        params = {"interval": interval, "limit": limit}
+        response = self._client._request(
+            "GET", f"/api/v1/markets/{market_id}/history", params=params
+        )
+        return response.get("history", [])
+
+    def get_trades(
+        self,
+        market_id: str,
+        limit: int = 50,
+    ) -> List[dict]:
+        """
+        Get recent trades for a market.
+
+        Args:
+            market_id: Market address
+            limit: Max trades to return
+
+        Returns:
+            List of trade objects
+        """
+        params = {"limit": limit}
+        response = self._client._request(
+            "GET", f"/api/v1/markets/{market_id}/trades", params=params
+        )
+        return response.get("trades", [])
+
+    def list_open(self, **kwargs) -> MarketListResponse:
+        """List open markets."""
+        return self.list(status="open", **kwargs)
+
+    def list_resolved(self, **kwargs) -> MarketListResponse:
+        """List resolved markets."""
+        return self.list(status="resolved", **kwargs)
+
+    def list_by_category(self, category: str, **kwargs) -> MarketListResponse:
+        """List markets by category."""
+        return self.list(category=category, **kwargs)

problee/api/positions.py

@@ -0,0 +1,49 @@
+"""
+Positions API
+"""
+
+from typing import Optional, TYPE_CHECKING
+from ..models.position import Position, PositionListResponse
+
+if TYPE_CHECKING:
+    from ..client import ProbClient
+
+
+class PositionsAPI:
+    """Positions API methods."""
+
+    def __init__(self, client: "ProbClient"):
+        self._client = client
+
+    def list(self, address: str) -> PositionListResponse:
+        """
+        Get all positions for a wallet address.
+
+        Args:
+            address: Wallet address (0x...)
+
+        Returns:
+            PositionListResponse with list of positions
+        """
+        response = self._client._request("GET", f"/api/v1/positions/{address}")
+        return PositionListResponse.from_dict(response)
+
+    def get(self, address: str, market_id: str) -> Optional[Position]:
+        """
+        Get position for a specific market.
+
+        Args:
+            address: Wallet address
+            market_id: Market address
+
+        Returns:
+            Position or None if no position
+        """
+        params = {"market_id": market_id}
+        response = self._client._request(
+            "GET", f"/api/v1/positions/{address}", params=params
+        )
+        positions = response.get("positions", [])
+        if positions:
+            return Position.from_dict(positions[0])
+        return None

problee/api/quotes.py

@@ -0,0 +1,85 @@
+"""
+Quotes API
+"""
+
+from typing import Optional, TYPE_CHECKING
+from ..models.quote import Quote, TransactionData
+
+if TYPE_CHECKING:
+    from ..client import ProbClient
+
+
+class QuotesAPI:
+    """Quotes API methods."""
+
+    def __init__(self, client: "ProbClient"):
+        self._client = client
+
+    def get(
+        self,
+        market_id: str,
+        side: str,
+        outcome: str,
+        amount: str,
+        slippage_bps: int = 50,
+    ) -> Quote:
+        """
+        Get a quote for a trade.
+
+        Args:
+            market_id: Market address
+            side: "buy" or "sell"
+            outcome: "yes", "no", or "draw"
+            amount: Amount in wei (as string)
+            slippage_bps: Slippage tolerance in basis points (default 50 = 0.5%)
+
+        Returns:
+            Quote object with price and execution details
+        """
+        payload = {
+            "market_id": market_id,
+            "side": side,
+            "outcome": outcome,
+            "amount": amount,
+            "slippage_bps": slippage_bps,
+        }
+        response = self._client._request("POST", "/api/v1/quote", json=payload)
+        return Quote.from_dict(response)
+
+    def get_buy_yes(self, market_id: str, amount: str, **kwargs) -> Quote:
+        """Get quote to buy YES shares."""
+        return self.get(market_id, "buy", "yes", amount, **kwargs)
+
+    def get_buy_no(self, market_id: str, amount: str, **kwargs) -> Quote:
+        """Get quote to buy NO shares."""
+        return self.get(market_id, "buy", "no", amount, **kwargs)
+
+    def get_sell_yes(self, market_id: str, amount: str, **kwargs) -> Quote:
+        """Get quote to sell YES shares."""
+        return self.get(market_id, "sell", "yes", amount, **kwargs)
+
+    def get_sell_no(self, market_id: str, amount: str, **kwargs) -> Quote:
+        """Get quote to sell NO shares."""
+        return self.get(market_id, "sell", "no", amount, **kwargs)
+
+    def build_transaction(
+        self,
+        quote_id: str,
+        rpc_url: str,
+    ) -> TransactionData:
+        """
+        Build transaction data from a quote.
+
+        Args:
+            quote_id: Quote ID from get() response
+            rpc_url: RPC URL for the chain
+
+        Returns:
+            TransactionData with calldata for execution
+        """
+        payload = {"quote_id": quote_id}
+        headers = {"X-RPC-URL": rpc_url}
+        response = self._client._request(
+            "POST", "/api/v1/tx/build", json=payload, headers=headers
+        )
+        return TransactionData.from_dict(response)

problee/client.py

@@ -0,0 +1,255 @@
+"""
+Problee API Client
+
+The main client class for interacting with the Problee API.
+"""
+
+import time
+from typing import Optional, Dict, Any
+from urllib.parse import urljoin
+
+import requests
+
+from .api.markets import MarketsAPI
+from .api.positions import PositionsAPI
+from .api.quotes import QuotesAPI
+from .streaming.sse import SSEClient
+from .streaming.websocket import WebSocketClient
+from .exceptions import (
+    ProbError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    APIError,
+)
+
+
+class ProbClient:
+    """
+    Problee API Client.
+
+    Example:
+        ```python
+        from problee import ProbClient
+
+        # Initialize client
+        client = ProbClient(api_key="pk_live_...")
+
+        # List open markets
+        markets = client.markets.list(status="open")
+        for market in markets.markets:
+            print(f"{market.question}: YES={market.prices.yes:.2%}")
+
+        # Get a quote
+        quote = client.quotes.get(
+            market_id="0x...",
+            side="buy",
+            outcome="yes",
+            amount="1000000000000000000"  # 1 USDC in wei
+        )
+        print(f"Price: {quote.price:.4f}, Shares: {quote.shares_out}")
+
+        # Check positions
+        positions = client.positions.list("0xYourWallet...")
+        ```
+
+    Attributes:
+        markets: Markets API
+        positions: Positions API
+        quotes: Quotes API
+        stream: SSE streaming client
+        ws: WebSocket client
+    """
+
+    DEFAULT_BASE_URL = "https://api.problee.com"
+    DEFAULT_TIMEOUT = 30
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+        builder_id: Optional[str] = None,
+    ):
+        """
+        Initialize the Problee client.
+
+        Args:
+            api_key: API key (pk_live_... or pk_test_...)
+            base_url: API base URL (defaults to https://api.problee.com)
+            timeout: Request timeout in seconds
+            max_retries: Max retries for failed requests
+            builder_id: Optional builder ID for attribution
+        """
+        self._api_key = api_key
+        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._builder_id = builder_id
+
+        # Initialize session
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "problee-python/0.1.0",
+        })
+
+        if api_key:
+            self._session.headers["Authorization"] = f"Bearer {api_key}"
+
+        if builder_id:
+            self._session.headers["X-Builder-ID"] = builder_id
+
+        # Initialize API modules
+        self.markets = MarketsAPI(self)
+        self.positions = PositionsAPI(self)
+        self.quotes = QuotesAPI(self)
+
+        # Initialize streaming clients (lazy)
+        self._sse_client: Optional[SSEClient] = None
+        self._ws_client: Optional[WebSocketClient] = None
+
+    @property
+    def stream(self) -> SSEClient:
+        """Get SSE streaming client."""
+        if self._sse_client is None:
+            self._sse_client = SSEClient(self._base_url, self._api_key)
+        return self._sse_client
+
+    @property
+    def ws(self) -> WebSocketClient:
+        """Get WebSocket client."""
+        if self._ws_client is None:
+            self._ws_client = WebSocketClient(self._base_url, self._api_key)
+        return self._ws_client
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make an API request.
+
+        Args:
+            method: HTTP method
+            path: API path
+            params: Query parameters
+            json: JSON body
+            headers: Additional headers
+
+        Returns:
+            Response JSON
+
+        Raises:
+            AuthenticationError: Invalid API key
+            RateLimitError: Rate limit exceeded
+            NotFoundError: Resource not found
+            ValidationError: Invalid request
+            APIError: Other API errors
+        """
+        url = urljoin(self._base_url, path)
+        request_headers = dict(self._session.headers)
+        if headers:
+            request_headers.update(headers)
+
+        last_exception = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = self._session.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                    headers=request_headers,
+                    timeout=self._timeout,
+                )
+
+                # Handle successful response
+                if response.ok:
+                    return response.json()
+
+                # Handle errors
+                self._handle_error(response)
+
+            except requests.exceptions.Timeout:
+                last_exception = APIError("Request timed out", code="TIMEOUT")
+            except requests.exceptions.ConnectionError:
+                last_exception = APIError("Connection failed", code="CONNECTION_ERROR")
+            except ProbError:
+                raise
+            except Exception as e:
+                last_exception = APIError(str(e))
+
+            # Retry with backoff
+            if attempt < self._max_retries - 1:
+                time.sleep(2 ** attempt)
+
+        if last_exception:
+            raise last_exception
+        raise APIError("Request failed after retries")
+
+    def _handle_error(self, response: requests.Response) -> None:
+        """Handle API error response."""
+        status_code = response.status_code
+
+        try:
+            data = response.json()
+            message = data.get("error", data.get("message", "Unknown error"))
+            code = data.get("code")
+        except Exception:
+            message = response.text or "Unknown error"
+            code = None
+
+        if status_code == 401:
+            raise AuthenticationError(message)
+        elif status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(
+                message,
+                retry_after=int(retry_after) if retry_after else None,
+            )
+        elif status_code == 404:
+            raise NotFoundError(message)
+        elif status_code == 400:
+            errors = data.get("errors") if isinstance(data, dict) else None
+            raise ValidationError(message, errors=errors)
+        else:
+            raise APIError(message, code=code, status_code=status_code)
+
+    def get_rate_limit_info(self) -> Dict[str, Any]:
+        """
+        Get current rate limit status.
+
+        Returns:
+            Dict with rate limit headers from last request
+        """
+        # Make a lightweight request to get headers
+        response = self._session.get(
+            urljoin(self._base_url, "/healthz"),
+            timeout=self._timeout,
+        )
+        return {
+            "limit": response.headers.get("RateLimit-Limit"),
+            "remaining": response.headers.get("RateLimit-Remaining"),
+            "reset": response.headers.get("RateLimit-Reset"),
+        }
+
+    def close(self) -> None:
+        """Close the client and clean up resources."""
+        self._session.close()
+        if self._sse_client:
+            self._sse_client.close()
+
+    def __enter__(self) -> "ProbClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

problee/exceptions.py

@@ -0,0 +1,84 @@
+"""
+Problee SDK Exceptions
+
+Custom exception classes for handling API errors.
+"""
+
+from typing import Optional, Dict, Any
+
+
+class ProbError(Exception):
+    """Base exception for all Problee SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.response = response
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(ProbError):
+    """Raised when API key is invalid or missing."""
+
+    def __init__(self, message: str = "Invalid or missing API key"):
+        super().__init__(message, code="AUTHENTICATION_ERROR", status_code=401)
+
+
+class RateLimitError(ProbError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[int] = None,
+    ):
+        super().__init__(message, code="RATE_LIMIT_EXCEEDED", status_code=429)
+        self.retry_after = retry_after
+
+
+class NotFoundError(ProbError):
+    """Raised when a resource is not found."""
+
+    def __init__(self, message: str = "Resource not found", resource_type: Optional[str] = None):
+        super().__init__(message, code="NOT_FOUND", status_code=404)
+        self.resource_type = resource_type
+
+
+class ValidationError(ProbError):
+    """Raised when request validation fails."""
+
+    def __init__(self, message: str, errors: Optional[list] = None):
+        super().__init__(message, code="VALIDATION_ERROR", status_code=400)
+        self.errors = errors or []
+
+
+class APIError(ProbError):
+    """Raised for general API errors."""
+
+    pass
+
+
+class QuoteExpiredError(ProbError):
+    """Raised when a quote has expired."""
+
+    def __init__(self, message: str = "Quote has expired"):
+        super().__init__(message, code="QUOTE_EXPIRED", status_code=400)
+
+
+class InsufficientSharesError(ProbError):
+    """Raised when user doesn't have enough shares."""
+
+    def __init__(self, message: str = "Insufficient shares"):
+        super().__init__(message, code="INSUFFICIENT_SHARES", status_code=400)

problee/models/__init__.py

@@ -0,0 +1,16 @@
+"""
+Problee SDK Data Models
+"""
+
+from .market import Market, MarketStatus, MarketCategory, MarketPrices
+from .position import Position
+from .quote import Quote
+
+__all__ = [
+    "Market",
+    "MarketStatus",
+    "MarketCategory",
+    "MarketPrices",
+    "Position",
+    "Quote",
+]