worm-sdk 0.9.0__py3-none-any.whl

worm_sdk/__init__.py

@@ -0,0 +1,62 @@
+"""Worm SDK — Python client for the Worm prediction markets platform."""
+
+from worm_sdk._version import __version__
+from worm_sdk.auth.signer import SignerProtocol
+from worm_sdk.client import WormClient
+from worm_sdk.exceptions import (
+    AuthenticationRequired,
+    SigningError,
+    WormAPIError,
+    WormSDKError,
+)
+from worm_sdk.types.auth import ApiKeyCredential
+from worm_sdk.types.common import CursorPage, ResponseContext
+from worm_sdk.types.enums import (
+    CandleInterval,
+    MarginActivityType,
+    MarginListSort,
+    MarginPolymarketMarketState,
+    MarginPositionRequestType,
+    MarginSettlementState,
+    MarketConfigKind,
+    MarketSortOption,
+    MarketStateFilter,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    PositionRequestState,
+    RedeemState,
+    SearchResultType,
+    SearchSortOption,
+    SearchStateFilter,
+)
+
+__all__ = [
+    "__version__",
+    "WormClient",
+    "SignerProtocol",
+    "ApiKeyCredential",
+    "CursorPage",
+    "ResponseContext",
+    "WormSDKError",
+    "WormAPIError",
+    "AuthenticationRequired",
+    "SigningError",
+    "MarginPositionRequestType",
+    "MarginListSort",
+    "MarginActivityType",
+    "MarginSettlementState",
+    "MarginPolymarketMarketState",
+    "MarketConfigKind",
+    "MarketSortOption",
+    "MarketStateFilter",
+    "CandleInterval",
+    "OrderSide",
+    "OrderStatus",
+    "OrderType",
+    "PositionRequestState",
+    "RedeemState",
+    "SearchResultType",
+    "SearchSortOption",
+    "SearchStateFilter",
+]

worm_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.9.0"

worm_sdk/api/__init__.py

@@ -0,0 +1,23 @@
+from worm_sdk.api.account import AccountAPI
+from worm_sdk.api.api_keys import ApiKeysAPI
+from worm_sdk.api.events import EventsAPI
+from worm_sdk.api.margin import MarginAPI
+from worm_sdk.api.markets import MarketsAPI
+from worm_sdk.api.orders import OrdersAPI
+from worm_sdk.api.redeems import RedeemsAPI
+from worm_sdk.api.search import SearchAPI
+from worm_sdk.api.sports import SportsAPI
+from worm_sdk.api.trades import TradesAPI
+
+__all__ = [
+    "AccountAPI",
+    "ApiKeysAPI",
+    "EventsAPI",
+    "MarginAPI",
+    "MarketsAPI",
+    "OrdersAPI",
+    "RedeemsAPI",
+    "SearchAPI",
+    "SportsAPI",
+    "TradesAPI",
+]

worm_sdk/api/account.py

@@ -0,0 +1,76 @@
+"""Account API — authenticated endpoints for user account data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from worm_sdk import constants
+from worm_sdk.http import SyncHTTPClient
+from worm_sdk.types.account import AccountPortfolioItem, AccountPnlBreakdown, AccountProfile
+from worm_sdk.types.common import CursorPage
+
+
+class AccountAPI:
+    """User account endpoints (authenticated)."""
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def get_summary(self) -> AccountProfile:
+        """Return account profile fields for the authenticated user.
+
+        Includes ``username``, ``twitter_username``, and ``joined_at``.
+        """
+        data, _ = self._http.get(endpoint=constants.ACCOUNT_SUMMARY, authenticated=True)
+        return AccountProfile.model_validate(obj=data)
+
+    def get_assets(
+        self,
+        market_condition_id: str | None = None,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> CursorPage[AccountPortfolioItem]:
+        """List spot market outcome share balances for the authenticated user.
+
+        Args:
+            market_condition_id: When set, return only share rows for this market.
+            limit: Maximum number of share rows to return.
+            cursor: Pagination cursor from a previous response.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if market_condition_id is not None:
+            params["market_condition_id"] = market_condition_id
+        if cursor is not None:
+            params["cursor"] = cursor
+
+        data, meta = self._http.get(endpoint=constants.ACCOUNT_ASSETS, params=params, authenticated=True)
+        items = [AccountPortfolioItem.model_validate(obj=row) for row in (data or [])]
+        return CursorPage[AccountPortfolioItem](
+            items=items,
+            next_cursor=meta.get("next_cursor"),
+            limit=meta.get("limit", limit),
+        )
+
+    def get_pnl(
+        self,
+        market_condition_id: str | None = None,
+        event_condition_id: str | None = None,
+    ) -> AccountPnlBreakdown:
+        """Return PnL breakdown for the authenticated user.
+
+        Args:
+            market_condition_id: Restrict PnL to a single market.
+            event_condition_id: Restrict PnL to a single event.
+        """
+        params: dict[str, Any] = {}
+        if market_condition_id is not None:
+            params["market_condition_id"] = market_condition_id
+        if event_condition_id is not None:
+            params["event_condition_id"] = event_condition_id
+
+        data, _ = self._http.get(
+            endpoint=constants.ACCOUNT_PNL,
+            params=params or None,
+            authenticated=True,
+        )
+        return AccountPnlBreakdown.model_validate(obj=data)

worm_sdk/api/api_keys.py

@@ -0,0 +1,29 @@
+"""API Keys API — authenticated endpoints for managing API keys."""
+
+from __future__ import annotations
+
+from worm_sdk import constants
+from worm_sdk.http import SyncHTTPClient
+from worm_sdk.types.auth import ApiKeyListItem
+
+
+class ApiKeysAPI:
+    """API key management endpoints (authenticated)."""
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def list(self) -> list[ApiKeyListItem]:
+        """List API keys owned by the authenticated account."""
+        data, _ = self._http.get(endpoint=constants.AUTH_KEYS_LIST, authenticated=True)
+        rows = data or []
+        return [ApiKeyListItem.model_validate(obj=row) for row in rows]
+
+    def revoke(self, key_id: str) -> ApiKeyListItem:
+        """Revoke an API key by ``key_id``.
+
+        Revoked keys can no longer authenticate requests.
+        """
+        url = constants.AUTH_KEYS_REVOKE.format(key_id=key_id)
+        data, _ = self._http.delete(endpoint=url, authenticated=True)
+        return ApiKeyListItem.model_validate(obj=data)

worm_sdk/api/events.py

@@ -0,0 +1,69 @@
+"""Events API — public endpoints for event data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from worm_sdk import constants
+from worm_sdk.http import SyncHTTPClient
+from worm_sdk.types.common import CursorPage
+from worm_sdk.types.enums import MarketSortOption, MarketStateFilter
+from worm_sdk.types.event import Event, EventDetail
+from worm_sdk.wire import enum_wire_value
+
+
+class EventsAPI:
+    """Public event data endpoints."""
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        state: MarketStateFilter | None = None,
+        category: str | None = None,
+        sort: MarketSortOption | str | None = None,
+        sport: str | None = None,
+        league: str | None = None,
+        limit: int = 20,
+        cursor: str | None = None,
+    ) -> CursorPage[Event]:
+        """List public events with filtering and cursor pagination.
+
+        Args:
+            state: Filter by market lifecycle state for events.
+            category: Filter by event category slug.
+            sort: Sort key: ``market_cap``, ``last_trade``, ``total_volume``, ``live_stream``,
+                ``trending``, ``leverage``, or ``ending_soon`` (see ``MarketSortOption``).
+            sport: Comma-separated sport slugs from ``client.sports.list()``.
+            league: Comma-separated league slugs from the sports catalog; requires ``sport``.
+            limit: Maximum number of events to return.
+            cursor: Pagination cursor from a previous response.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if state is not None:
+            params["state"] = state.value
+        if category is not None:
+            params["category"] = category
+        if sort is not None:
+            params["sort"] = enum_wire_value(value=sort, enum_cls=MarketSortOption)
+        if sport is not None:
+            params["sport"] = sport
+        if league is not None:
+            params["league"] = league
+
+        data, meta = self._http.get(endpoint=constants.EVENTS_LIST, params=params)
+        items = [Event.model_validate(obj=e) for e in (data or [])]
+        return CursorPage[Event](
+            items=items,
+            next_cursor=meta.get("next_cursor"),
+            limit=meta.get("limit", limit),
+        )
+
+    def get(self, condition_id: str) -> EventDetail:
+        """Fetch full event details by event ``condition_id``."""
+        url = constants.EVENT_DETAIL.format(condition_id=condition_id)
+        data, _ = self._http.get(endpoint=url)
+        return EventDetail.model_validate(obj=data)

worm_sdk/api/margin.py

@@ -0,0 +1,388 @@
+"""Margin API — authenticated endpoints for margin position management."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from decimal import Decimal
+from typing import Any
+
+from worm_sdk import constants
+from worm_sdk.auth.signer import SignerProtocol
+from worm_sdk.http import SyncHTTPClient
+from worm_sdk.types.common import CursorPage
+from worm_sdk.types.enums import (
+    MarginListSort,
+    MarginPolymarketMarketState,
+    MarginPositionRequestType,
+    MarginSettlementState,
+    PositionRequestState,
+)
+from worm_sdk.types.margin import (
+    MarginCloseResponse,
+    MarginEstimate,
+    MarginSettlementClaimResponse,
+    Position,
+    PositionRequest,
+    PositionTpSl,
+    Settlement,
+)
+from worm_sdk.wire import comma_join_enum_wire, enum_wire_value
+
+
+class MarginAPI:
+    """Margin trading endpoints."""
+
+    def __init__(self, http: SyncHTTPClient, signer: SignerProtocol | None = None) -> None:
+        self._http = http
+        self._signer = signer
+
+    # --- Public ---
+
+    def estimate(
+        self,
+        market_condition_id: str,
+        funds: Decimal | str | int,
+        leverage: Decimal | str | int | None = None,
+        is_yes: bool = True,
+    ) -> MarginEstimate:
+        """Estimate margin position metrics before opening a position.
+
+        Public endpoint; authentication is not required.
+        """
+        params: dict[str, Any] = {
+            "market_condition_id": market_condition_id,
+            "funds": str(funds),
+            "is_yes": is_yes,
+        }
+        if leverage is not None:
+            params["leverage"] = str(leverage)
+
+        data, _ = self._http.get(endpoint=constants.MARGIN_ESTIMATE, params=params)
+        return MarginEstimate.model_validate(obj=data)
+
+    # --- Positions ---
+
+    def list_positions(
+        self,
+        market_condition_id: str | None = None,
+        is_closed: bool | None = None,
+        sort: MarginListSort | str = MarginListSort.CREATED_DESC,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> CursorPage[Position]:
+        """List margin positions for the authenticated user.
+
+        Args:
+            market_condition_id: Filter to a specific market.
+            is_closed: ``True`` for closed only, ``False`` for open only, ``None`` for both.
+            sort: ``created`` or ``-created`` (default ``-created``); see ``MarginListSort``.
+            limit: Maximum number of positions to return.
+            cursor: Pagination cursor from a previous response.
+        """
+        params: dict[str, Any] = {
+            "limit": limit,
+            "sort": enum_wire_value(value=sort, enum_cls=MarginListSort),
+        }
+        if cursor is not None:
+            params["cursor"] = cursor
+        if market_condition_id is not None:
+            params["market_condition_id"] = market_condition_id
+        if is_closed is not None:
+            params["is_closed"] = is_closed
+
+        data, meta = self._http.get(endpoint=constants.MARGIN_POSITIONS, params=params, authenticated=True)
+        items = [Position.model_validate(obj=row) for row in (data or [])]
+        return CursorPage[Position](
+            items=items,
+            next_cursor=meta.get("next_cursor"),
+            limit=meta.get("limit", limit),
+        )
+
+    def get_position(self, pubkey: str) -> Position:
+        """Fetch a single margin position by ``pubkey``."""
+        url = constants.MARGIN_POSITION_DETAIL.format(pubkey=pubkey)
+        data, _ = self._http.get(endpoint=url, authenticated=True)
+        return Position.model_validate(obj=data)
+
+    def close_position(
+        self,
+        pubkey: str,
+        price: Decimal | str | int | None = None,
+    ) -> MarginCloseResponse:
+        """Close a margin position.
+
+        Args:
+            pubkey: Position identifier.
+            price: Optional limit/target close price.
+        """
+        url = constants.MARGIN_POSITION_CLOSE.format(pubkey=pubkey)
+        params: dict[str, Any] = {}
+        if price is not None:
+            params["price"] = str(price)
+        data, _ = self._http.delete(endpoint=url, params=params or None, authenticated=True)
+        return MarginCloseResponse.model_validate(obj=data)
+
+    # --- Position Requests ---
+
+    def list_requests(
+        self,
+        market_condition_id: str | None = None,
+        states: PositionRequestState | str | Iterable[PositionRequestState] | None = None,
+        is_yes: bool | None = None,
+        leverage: Decimal | str | int | None = None,
+        sort: MarginListSort | str = MarginListSort.CREATED_DESC,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> CursorPage[PositionRequest]:
+        """List margin position requests for the authenticated user.
+
+        Use this to inspect pending, submitted, filled, or canceled requests.
+
+        Args:
+            market_condition_id: Filter to a specific market.
+            states: Comma-separated request state filters (see ``PositionRequestState`` wire values)
+                or an iterable of enum members.
+            is_yes: Filter by outcome side.
+            leverage: Filter by leverage value.
+            sort: ``created`` or ``-created`` (default ``-created``); see ``MarginListSort``.
+            limit: Maximum number of requests to return.
+            cursor: Pagination cursor from a previous response.
+        """
+        params: dict[str, Any] = {
+            "limit": limit,
+            "sort": enum_wire_value(value=sort, enum_cls=MarginListSort),
+        }
+        if cursor is not None:
+            params["cursor"] = cursor
+        if market_condition_id is not None:
+            params["market_condition_id"] = market_condition_id
+        if states is not None:
+            params["states"] = comma_join_enum_wire(value=states, enum_cls=PositionRequestState)
+        if is_yes is not None:
+            params["is_yes"] = is_yes
+        if leverage is not None:
+            params["leverage"] = str(leverage)
+
+        data, meta = self._http.get(endpoint=constants.MARGIN_REQUESTS, params=params, authenticated=True)
+        items = [PositionRequest.model_validate(obj=row) for row in (data or [])]
+        return CursorPage[PositionRequest](
+            items=items,
+            next_cursor=meta.get("next_cursor"),
+            limit=meta.get("limit", limit),
+        )
+
+    def get_request(self, pubkey: str) -> PositionRequest:
+        """Fetch a single margin request by ``pubkey``."""
+        url = constants.MARGIN_REQUEST_DETAIL.format(pubkey=pubkey)
+        data, _ = self._http.get(endpoint=url, authenticated=True)
+        return PositionRequest.model_validate(obj=data)
+
+    def create_request(
+        self,
+        market_condition_id: str,
+        position_request_type: MarginPositionRequestType | str,
+        funds: Decimal | str | int | None = None,
+        is_yes: bool = True,
+        leverage: Decimal | str | int | None = None,
+        price: Decimal | str | int | None = None,
+        shares: Decimal | str | int | None = None,
+        take_profit_price: Decimal | str | int | None = None,
+        stop_loss_price: Decimal | str | int | None = None,
+    ) -> PositionRequest:
+        """Create an unsigned margin position request draft.
+
+        ``position_request_type`` must be ``market`` (pass ``funds``) or ``limit``
+        (pass ``price`` and ``shares``). The API rejects mixed combinations.
+
+        The response includes ``pubkey`` and signing ``message``. Sign and submit
+        with ``submit_request()``.
+        """
+        ptype = self._margin_request_type_json(value=position_request_type)
+        payload: dict[str, Any] = {
+            "type": ptype,
+            "market_condition_id": market_condition_id,
+            "is_yes": is_yes,
+        }
+        if leverage is not None:
+            payload["leverage"] = str(leverage)
+        if ptype == MarginPositionRequestType.MARKET.value:
+            if funds is None:
+                raise ValueError("funds is required when position_request_type is market")
+            payload["funds"] = str(funds)
+        else:
+            if price is None or shares is None:
+                raise ValueError("price and shares are required when position_request_type is limit")
+            payload["price"] = str(price)
+            payload["shares"] = str(shares)
+        if take_profit_price is not None:
+            payload["take_profit_price"] = str(take_profit_price)
+        if stop_loss_price is not None:
+            payload["stop_loss_price"] = str(stop_loss_price)
+
+        data, _ = self._http.post(endpoint=constants.MARGIN_REQUESTS, json=payload, authenticated=True)
+        return PositionRequest.model_validate(obj=data)
+
+    def cancel_request(self, pubkey: str) -> PositionRequest:
+        """Cancel a pending margin request by ``pubkey``."""
+        url = constants.MARGIN_REQUEST_DETAIL.format(pubkey=pubkey)
+        data, _ = self._http.delete(endpoint=url, authenticated=True)
+        return PositionRequest.model_validate(obj=data)
+
+    def submit_request(
+        self,
+        pubkey: str,
+        signature: str,
+    ) -> PositionRequest:
+        """Submit a hex signature over the position-request draft ``message``."""
+        url = constants.MARGIN_REQUEST_SUBMIT.format(pubkey=pubkey)
+        data, _ = self._http.post(
+            endpoint=url,
+            json={"signature": signature},
+            authenticated=True,
+        )
+        return PositionRequest.model_validate(obj=data)
+
+    def open_position(
+        self,
+        market_condition_id: str,
+        position_request_type: MarginPositionRequestType | str,
+        funds: Decimal | str | int | None = None,
+        is_yes: bool = True,
+        leverage: Decimal | str | int | None = None,
+        price: Decimal | str | int | None = None,
+        shares: Decimal | str | int | None = None,
+        take_profit_price: Decimal | str | int | None = None,
+        stop_loss_price: Decimal | str | int | None = None,
+    ) -> PositionRequest:
+        """Convenience: create request + auto-sign + submit in one call.
+
+        Requires a ``signer`` configured on ``WormClient``.
+        """
+        from worm_sdk.exceptions import SigningError
+
+        if self._signer is None:
+            raise SigningError("A signer is required for open_position(). Pass signer= to WormClient.")
+
+        request_data = self.create_request(
+            market_condition_id=market_condition_id,
+            position_request_type=position_request_type,
+            funds=funds,
+            is_yes=is_yes,
+            leverage=leverage,
+            price=price,
+            shares=shares,
+            take_profit_price=take_profit_price,
+            stop_loss_price=stop_loss_price,
+        )
+        message = request_data.message
+        if not message:
+            raise SigningError("Margin request draft did not include a signable message.")
+        if not request_data.pubkey:
+            raise SigningError("Margin request draft did not include a pubkey.")
+        signature = self._signer.sign_transaction(transaction_hex=message)
+        return self.submit_request(pubkey=request_data.pubkey, signature=signature)
+
+    # --- TP/SL ---
+
+    def set_tp_sl(
+        self,
+        pubkey: str,
+        take_profit_price: Decimal | str | int | None = None,
+        stop_loss_price: Decimal | str | int | None = None,
+    ) -> PositionTpSl:
+        """Set or update take-profit / stop-loss values on a position."""
+        payload: dict[str, Any] = {}
+        if take_profit_price is not None:
+            payload["take_profit_price"] = str(take_profit_price)
+        if stop_loss_price is not None:
+            payload["stop_loss_price"] = str(stop_loss_price)
+        if not any(k in payload for k in ("take_profit_price", "stop_loss_price")):
+            raise ValueError("Provide at least one of take_profit_price= or stop_loss_price=.")
+
+        url = constants.MARGIN_POSITION_TP_SL.format(pubkey=pubkey)
+        data, _ = self._http.post(endpoint=url, json=payload, authenticated=True)
+        return PositionTpSl.model_validate(obj=data)
+
+    def remove_tp_sl(self, pubkey: str) -> PositionTpSl:
+        """Remove both take-profit and stop-loss settings from a position."""
+        url = constants.MARGIN_POSITION_TP_SL.format(pubkey=pubkey)
+        data, _ = self._http.delete(endpoint=url, authenticated=True)
+        return PositionTpSl.model_validate(obj=data)
+
+    # --- Settlements ---
+
+    def claim_settlement(self, pubkey: str) -> MarginSettlementClaimResponse:
+        """Claim settlement funds for an eligible position."""
+        url = constants.MARGIN_POSITION_SETTLEMENTS_ACTION.format(pubkey=pubkey)
+        data, _ = self._http.post(endpoint=url, authenticated=True)
+        return MarginSettlementClaimResponse.model_validate(obj=data)
+
+    def list_settlements(
+        self,
+        position_pubkey: str | None = None,
+        market_condition_id: str | None = None,
+        states: MarginSettlementState | str | Iterable[MarginSettlementState] | None = None,
+        market_state: MarginPolymarketMarketState | str | None = None,
+        position_leverage: Decimal | str | int | None = None,
+        sort: MarginListSort | str = MarginListSort.CREATED_DESC,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> CursorPage[Settlement]:
+        """List settlement records across the user's margin positions.
+
+        Args:
+            position_pubkey: Filter by margin position pubkey.
+            market_condition_id: Filter by market.
+            states: Comma-separated settlement state filters (see ``MarginSettlementState``) or
+                an iterable of enum members.
+            market_state: Market lifecycle filter for this list (``open`` / ``resolved``).
+            position_leverage: Filter by position leverage.
+            sort: ``created`` or ``-created`` (default ``-created``).
+            limit: Page size.
+            cursor: Pagination cursor.
+        """
+        params: dict[str, Any] = {
+            "limit": limit,
+            "sort": enum_wire_value(value=sort, enum_cls=MarginListSort),
+        }
+        if cursor is not None:
+            params["cursor"] = cursor
+        if position_pubkey is not None:
+            params["position_pubkey"] = position_pubkey
+        if market_condition_id is not None:
+            params["market_condition_id"] = market_condition_id
+        if states is not None:
+            params["states"] = comma_join_enum_wire(value=states, enum_cls=MarginSettlementState)
+        if market_state is not None:
+            params["market_state"] = self._normalize_market_state_wire(value=market_state)
+        if position_leverage is not None:
+            params["position_leverage"] = str(position_leverage)
+
+        data, meta = self._http.get(endpoint=constants.MARGIN_SETTLEMENTS, params=params, authenticated=True)
+        items = [Settlement.model_validate(obj=row) for row in (data or [])]
+        return CursorPage[Settlement](
+            items=items,
+            next_cursor=meta.get("next_cursor"),
+            limit=meta.get("limit", limit),
+        )
+
+    @staticmethod
+    def _margin_request_type_json(value: MarginPositionRequestType | str) -> str:
+        normalized = enum_wire_value(value=value, enum_cls=MarginPositionRequestType)
+        if normalized not in (
+            MarginPositionRequestType.MARKET.value,
+            MarginPositionRequestType.LIMIT.value,
+        ):
+            raise ValueError(f'position_request_type must be market or limit, got {value!r}')
+        return normalized
+
+    @staticmethod
+    def _normalize_market_state_wire(value: MarginPolymarketMarketState | str) -> str:
+        normalized = enum_wire_value(value=value, enum_cls=MarginPolymarketMarketState)
+        allowed = {
+            MarginPolymarketMarketState.OPEN.value,
+            MarginPolymarketMarketState.RESOLVED.value,
+        }
+        if normalized not in allowed:
+            raise ValueError(f"market_state must be open or resolved, got {value!r}")
+        return normalized