Merge pull request #2 from perps-studio/claude/recursing-goodall-4c5a39

feat: initial port from ts

Author: dennisfurrer

README.md

@@ -48,7 +48,7 @@ from hip4.types import PredictionOrderParams
 adapter = create_hip4_adapter()
 adapter.initialize()
 
-# Agent key (separate from the user's wallet — sign with the user's wallet
+# Agent key (separate from the user's wallet - sign with the user's wallet
 # once via auth_eoa.py to approve, then store the agent key for trading).
 agent = LocalSigner(os.environ["HIP4_AGENT_PRIVATE_KEY"])
 adapter.auth.init_auth(os.environ["HIP4_USER_ADDRESS"], agent)
@@ -222,4 +222,4 @@ Signing implementation inspired by [`@nktkas/hyperliquid`](https://github.com/nk
 
 ## License
 
-BUSL-1.1 — same as the TypeScript SDK.
+BUSL-1.1 - same as the TypeScript SDK.

examples/async_get_all_markets.py

@@ -1,4 +1,4 @@
-"""Async equivalent of ``get_all_markets.py`` — requires ``hip4[async]``."""
+"""Async equivalent of ``get_all_markets.py`` - requires ``hip4[async]``."""
 
 from __future__ import annotations
 

examples/auth_eoa.py

@@ -32,14 +32,14 @@ def main() -> None:
     adapter = create_hip4_adapter()
     adapter.client.testnet = not is_mainnet  # already true by default; explicit here for clarity.
 
-    # 2. User's wallet (in real life this is the connected wallet — Metamask, etc.)
+    # 2. User's wallet (in real life this is the connected wallet - Metamask, etc.)
     user_pk = os.environ.get("HIP4_USER_PRIVATE_KEY")
     if not user_pk:
         raise SystemExit("Set HIP4_USER_PRIVATE_KEY to a hex private key for this demo.")
     user_signer = LocalSigner(user_pk)
     user_address = user_signer.get_address()
 
-    # 3. Agent key — a fresh, scoped signer used for order signing only.
+    # 3. Agent key - a fresh, scoped signer used for order signing only.
     agent_signer = LocalSigner.create()
     agent_address = agent_signer.get_address()
     agent_name = "hip4-py-demo"
@@ -63,7 +63,7 @@ def main() -> None:
     )
     print("approve_agent:", result)
 
-    # 6. Wire the agent into the adapter — orders are now signed by the agent
+    # 6. Wire the agent into the adapter - orders are now signed by the agent
     #    on behalf of the user's address.
     adapter.auth.init_auth(user_address, agent_signer)
     print("auth status:", adapter.auth.get_auth_status())

hip4/__init__.py

@@ -1,4 +1,4 @@
-"""hip4 — Python SDK for Hyperliquid HIP-4 prediction markets.
+"""hip4 - Python SDK for Hyperliquid HIP-4 prediction markets.
 
 Quick start (synchronous)::
 

hip4/_events_core.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import replace
-from typing import Dict, List, Mapping, Optional, Tuple
+from typing import Any, Dict, List, Mapping, Optional, Tuple
 
 from hip4.coin import side_coin
 from hip4.types.event import (
@@ -16,6 +16,7 @@
 
 __all__ = [
     "CATEGORIES",
+    "apply_outcome_created_to_side_names",
     "build_events_from_meta",
     "extract_side_names",
     "merge_mids_into_events",
@@ -156,6 +157,24 @@ def build_events_from_meta(meta: HLOutcomeMeta) -> List[PredictionEvent]:
     return events
 
 
+def apply_outcome_created_to_side_names(
+    side_names: Dict[int, Tuple[str, str]],
+    spec: Mapping[str, Any],
+) -> None:
+    """Mutate *side_names* to include a newly-created outcome from a WS update.
+
+    No-op if the spec doesn't carry both side names (under-specified outcome).
+    Mirrors the TS adapter's behaviour: extend in place so callers using
+    :meth:`get_side_name_resolver` pick up the new outcome immediately.
+    """
+    side_specs = spec.get("sideSpecs") or []
+    if len(side_specs) >= 2:
+        side_names[spec["outcome"]] = (
+            side_specs[0].get("name", "Side 0"),
+            side_specs[1].get("name", "Side 1"),
+        )
+
+
 def extract_side_names(meta: HLOutcomeMeta) -> Dict[int, Tuple[str, str]]:
     """Build the ``outcome_id -> (side0, side1)`` map used by the side-name resolver."""
     out: Dict[int, Tuple[str, str]] = {}

hip4/aio/__init__.py

@@ -5,8 +5,8 @@
     pip install hip4[async]
 
 Main entry points:
-  * :class:`AsyncHIP4Client` — low-level async info / exchange / WebSocket client.
-  * :class:`AsyncHIP4Adapter` — high-level async facade.
+  * :class:`AsyncHIP4Client` - low-level async info / exchange / WebSocket client.
+  * :class:`AsyncHIP4Adapter` - high-level async facade.
 """
 
 from hip4.aio.account import AsyncAccountAdapter
@@ -20,6 +20,11 @@
 from hip4.aio.events import AsyncEventsAdapter, SideNameResolver
 from hip4.aio.market_data import AsyncMarketDataAdapter, Candle
 from hip4.aio.ramp import AsyncRampAdapter
+from hip4.aio.streams.perp_price_feed import (
+    PerpPriceFeedOptions,
+    PerpPriceFeedSnapshot,
+    create_async_perp_price_feed,
+)
 from hip4.aio.streams.price_feed import (
     PriceFeedOptions,
     PriceFeedSnapshot,
@@ -63,6 +68,8 @@
     "MergeOutcomeParams",
     "MergeQuestionParams",
     "NegateOutcomeParams",
+    "PerpPriceFeedOptions",
+    "PerpPriceFeedSnapshot",
     "PriceFeedOptions",
     "PriceFeedSnapshot",
     "SendAssetParams",
@@ -78,6 +85,7 @@
     "WalletActionResult",
     "WithdrawParams",
     "create_async_hip4_adapter",
+    "create_async_perp_price_feed",
     "create_async_price_feed",
     "format_prediction_price",
 ]

hip4/aio/account.py

@@ -1,4 +1,4 @@
-"""Async account adapter — positions, activity, balances, open orders, position subscription."""
+"""Async account adapter - positions, activity, balances, open orders, position subscription."""
 
 from __future__ import annotations
 

hip4/aio/auth.py

@@ -1,4 +1,4 @@
-"""Async auth adapter — same surface as :class:`hip4.sync.AuthAdapter` but ``async``-flavoured.
+"""Async auth adapter - same surface as :class:`hip4.sync.AuthAdapter` but ``async``-flavoured.
 
 The actual signer state is identical (sync or async); we only add ``async``
 versions of the public methods so async callers don't need ``run_in_executor``.

hip4/aio/client.py

@@ -1,7 +1,7 @@
 """Asynchronous Hyperliquid HIP-4 HTTP + WebSocket client.
 
 Mirror of :mod:`hip4.sync.client` using ``httpx`` (HTTP) and ``websockets``
-(WebSocket). Both are optional dependencies — install with ``pip install
+(WebSocket). Both are optional dependencies - install with ``pip install
 hip4[async]``.
 """
 

hip4/aio/events.py

@@ -4,18 +4,19 @@
 
 import asyncio
 import time
-from typing import Callable, Dict, List, Optional, Tuple, Union
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple, Union
 
 from hip4._events_core import (
     CATEGORIES,
+    apply_outcome_created_to_side_names,
     build_events_from_meta,
     extract_side_names,
     merge_mids_into_events,
 )
 from hip4.aio.client import AsyncHIP4Client
 from hip4.market_classification import classify_all_outcomes
 from hip4.types.event import PredictionCategory, PredictionEvent
-from hip4.types.hl import HLSettledOutcome
+from hip4.types.hl import HLSettledOutcome, HLWsOutcomeMetaUpdate
 from hip4.types.hip4_market import (
     FetchMarketsParams,
     HIP4Market,
@@ -27,7 +28,7 @@
 __all__ = ["AsyncEventsAdapter", "SideNameResolver"]
 
 SideNameResolver = Callable[[int], Optional[Tuple[str, str]]]
-"""Resolve side names for an outcome by ID (sync — pure data lookup)."""
+"""Resolve side names for an outcome by ID (sync - pure data lookup)."""
 
 CACHE_TTL_S = 30.0
 
@@ -115,6 +116,39 @@ async def fetch_markets(
     async def fetch_settled_outcome(self, outcome_id: int) -> Optional[HLSettledOutcome]:
         return await self._client.fetch_settled_outcome(outcome_id)
 
+    # -- subscriptions -----------------------------------------------------
+
+    async def subscribe_outcome_meta_updates(
+        self,
+        on_data: Callable[[HLWsOutcomeMetaUpdate], Any],
+    ) -> Callable[[], Awaitable[None]]:
+        """Subscribe to live outcome-meta updates. See sync equivalent for details.
+
+        ``on_data`` may be sync or a coroutine; coroutines are scheduled with
+        ``asyncio.create_task``.
+        """
+        import asyncio  # local import keeps cold-start lazy
+
+        def _route(raw: Any) -> None:
+            if not isinstance(raw, list):
+                return
+            for update in raw:
+                if not isinstance(update, dict):
+                    continue
+                self._apply_meta_update(update)
+                result = on_data(update)
+                if asyncio.iscoroutine(result):
+                    asyncio.create_task(result)
+
+        return await self._client.subscribe({"type": "outcomeMetaUpdates"}, _route)
+
+    def _apply_meta_update(self, update: HLWsOutcomeMetaUpdate) -> None:
+        if "outcomeCreated" in update:
+            apply_outcome_created_to_side_names(self._side_names, update["outcomeCreated"])
+        # Drop time-based caches so the next read refetches.
+        self._events_cache = None
+        self._meta_cache = None
+
     # -- internals ---------------------------------------------------------
 
     async def _load_events(self) -> List[PredictionEvent]: