oxarchive 0.3.0__py3-none-any.whl → 0.3.6__py3-none-any.whl

oxarchive/__init__.py

@@ -57,7 +57,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.1.0"
+__version__ = "0.3.6"
 
 __all__ = [
     # Client

oxarchive/http.py

@@ -50,13 +50,26 @@ class HttpClient:
         return self._async_client
 
     def close(self) -> None:
-        """Close the HTTP clients."""
+        """Close the HTTP clients.
+
+        Note: This closes the sync client immediately. For the async client,
+        use aclose() instead, or call this from a sync context where you
+        don't need to await the async cleanup.
+        """
         if self._client is not None:
             self._client.close()
             self._client = None
         if self._async_client is not None:
-            # Note: async client should be closed with await
-            pass
+            # Close async client synchronously (will log warning but works)
+            # For proper cleanup, use aclose() in async contexts
+            try:
+                import asyncio
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._async_client.aclose())
+            except RuntimeError:
+                # No running loop, close synchronously (httpx supports this)
+                self._async_client.close()
+            self._async_client = None
 
     async def aclose(self) -> None:
         """Close the async HTTP client."""

oxarchive/types.py

@@ -118,17 +118,23 @@ class Trade(BaseModel):
     closed_pnl: Optional[str] = None
     """Realized PnL if closing a position."""
 
-    direction: Optional[Literal["Open Long", "Open Short", "Close Long", "Close Short"]] = None
-    """Position direction."""
+    direction: Optional[str] = None
+    """Position direction (e.g., 'Open Long', 'Close Short', 'Long > Short')."""
 
     start_position: Optional[str] = None
     """Position size before this trade."""
 
-    source: Optional[Literal["s3", "ws", "api"]] = None
-    """Data source."""
+    source: Optional[Literal["s3", "ws", "api", "live"]] = None
+    """Data source: 's3' (historical), 'api' (REST backfill), 'ws' (websocket), 'live' (real-time ingestion)."""
 
     user_address: Optional[str] = None
-    """User's wallet address."""
+    """User's wallet address (for fill-level data)."""
+
+    maker_address: Optional[str] = None
+    """Maker's wallet address (for market-level WebSocket trades)."""
+
+    taker_address: Optional[str] = None
+    """Taker's wallet address (for market-level WebSocket trades)."""
 
 
 # =============================================================================
@@ -261,12 +267,17 @@ class WsError(BaseModel):
 
 
 class WsData(BaseModel):
-    """Real-time data message from server."""
+    """Real-time data message from server.
+
+    Note: The `data` field can be either a dict (for orderbook) or a list (for trades).
+    - Orderbook: dict with 'levels', 'time', etc.
+    - Trades: list of trade objects with 'coin', 'side', 'px', 'sz', etc.
+    """
 
     type: Literal["data"]
     channel: WsChannel
     coin: str
-    data: dict[str, Any]
+    data: Union[dict[str, Any], list[dict[str, Any]]]
 
 
 # =============================================================================

oxarchive/websocket.py

@@ -120,6 +120,74 @@ StreamProgressHandler = Callable[[int], None]  # snapshots_sent
 StreamCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
 
+def _transform_trade(coin: str, raw: dict) -> Trade:
+    """Transform raw Hyperliquid trade format to SDK Trade type.
+
+    Raw WebSocket format: { coin, side, px, sz, time, hash, tid, users: [maker, taker] }
+    Historical replay format: { coin, side, price, size, time, hash, tradeId, userAddress, ... }
+    SDK format: { coin, side, price, size, timestamp, tx_hash, trade_id, maker_address, taker_address }
+    """
+    from datetime import datetime
+
+    # Check if already in SDK format (from REST API or historical replay)
+    if "price" in raw and "size" in raw:
+        # Map camelCase keys from WebSocket to snake_case for Pydantic
+        mapped = {
+            "coin": raw.get("coin", coin),
+            "side": raw.get("side", "B"),
+            "price": raw.get("price"),
+            "size": raw.get("size"),
+            "timestamp": raw.get("timestamp") or (datetime.utcfromtimestamp(raw.get("time", 0) / 1000).isoformat() + "Z" if raw.get("time") else None),
+            "tx_hash": raw.get("tx_hash") or raw.get("hash"),
+            "trade_id": raw.get("trade_id") or raw.get("tradeId"),
+            "order_id": raw.get("order_id") or raw.get("orderId"),
+            "crossed": raw.get("crossed"),
+            "fee": raw.get("fee"),
+            "fee_token": raw.get("fee_token") or raw.get("feeToken"),
+            "closed_pnl": raw.get("closed_pnl") or raw.get("closedPnl"),
+            "direction": raw.get("direction"),
+            "start_position": raw.get("start_position") or raw.get("startPosition"),
+            "source": raw.get("source"),
+            "user_address": raw.get("user_address") or raw.get("userAddress"),
+            "maker_address": raw.get("maker_address"),
+            "taker_address": raw.get("taker_address"),
+        }
+        # Remove None values to let Pydantic use defaults
+        mapped = {k: v for k, v in mapped.items() if v is not None}
+        return Trade(**mapped)
+
+    # Transform from Hyperliquid raw format
+    time_ms = raw.get("time")
+    timestamp = datetime.utcfromtimestamp(time_ms / 1000).isoformat() + "Z" if time_ms else None
+
+    # Extract maker/taker addresses from users array
+    # WebSocket trades have: users: [maker_address, taker_address]
+    users = raw.get("users", [])
+    maker_address = users[0] if len(users) > 0 else None
+    taker_address = users[1] if len(users) > 1 else None
+
+    return Trade(
+        coin=raw.get("coin", coin),
+        side=raw.get("side", "B"),
+        price=str(raw.get("px", "0")),
+        size=str(raw.get("sz", "0")),
+        timestamp=timestamp,
+        tx_hash=raw.get("hash"),
+        trade_id=raw.get("tid"),
+        maker_address=maker_address,
+        taker_address=taker_address,
+        # user_address is for fill-level data (REST API), not market-level WebSocket trades
+        user_address=raw.get("user_address"),
+    )
+
+
+def _transform_trades(coin: str, raw_data: list) -> list[Trade]:
+    """Transform a list of raw trades to SDK Trade types."""
+    if not isinstance(raw_data, list):
+        return [_transform_trade(coin, raw_data)]
+    return [_transform_trade(coin, t) for t in raw_data]
+
+
 def _transform_orderbook(coin: str, raw: dict) -> OrderBook:
     """Transform raw Hyperliquid orderbook format to SDK OrderBook type.
 
@@ -642,7 +710,8 @@ class OxArchiveWs:
                     self._on_orderbook(coin, orderbook)
 
                 elif channel == "trades" and self._on_trades:
-                    trades = [Trade(**t) for t in raw_data]
+                    # Transform raw Hyperliquid format to SDK Trade type
+                    trades = _transform_trades(coin, raw_data)
                     self._on_trades(coin, trades)
 
             # Replay messages (Option B)

{oxarchive-0.3.0.dist-info → oxarchive-0.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.0
+Version: 0.3.6
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -28,6 +28,7 @@ Requires-Dist: websockets>=12.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.9.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Provides-Extra: websocket
@@ -44,6 +45,12 @@ Official Python SDK for [0xarchive](https://0xarchive.io) - Hyperliquid Historic
 pip install oxarchive
 ```
 
+For WebSocket support:
+
+```bash
+pip install oxarchive[websocket]
+```
+
 ## Quick Start
 
 ```python
@@ -96,13 +103,13 @@ async with Client(api_key="ox_your_api_key") as client:
 
 ```python
 client = Client(
-    api_key="ox_your_api_key",      # Required
-    base_url="https://api.0xarchive.io",  # Optional
-    timeout=30.0,                    # Optional, request timeout in seconds
+    api_key="ox_your_api_key",           # Required
+    base_url="https://api.0xarchive.io", # Optional
+    timeout=30.0,                         # Optional, request timeout in seconds (default: 30.0)
 )
 ```
 
-## API Reference
+## REST API Reference
 
 ### Order Book
 
@@ -116,38 +123,63 @@ historical = client.orderbook.get("BTC", timestamp=1704067200000)
 # Get with limited depth
 shallow = client.orderbook.get("BTC", depth=10)
 
-# Get historical snapshots
+# Get historical snapshots (start and end are required)
 history = client.orderbook.history(
     "BTC",
     start="2024-01-01",
     end="2024-01-02",
-    limit=1000
+    limit=1000,
+    depth=20  # Price levels per side
 )
+
+# Async versions
+orderbook = await client.orderbook.aget("BTC")
+history = await client.orderbook.ahistory("BTC", start=..., end=...)
 ```
 
 ### Trades
 
+The trades API uses cursor-based pagination for efficient retrieval of large datasets.
+
 ```python
 # Get recent trades
 recent = client.trades.recent("BTC", limit=100)
 
-# Get trade history
-trades = client.trades.list(
-    "ETH",
-    start="2024-01-01",
-    end="2024-01-02",
-    side="buy"  # Optional: filter by side
-)
+# Get trade history with cursor-based pagination
+result = client.trades.list("ETH", start="2024-01-01", end="2024-01-02", limit=1000)
+trades = result.data
+
+# Paginate through all results
+while result.next_cursor:
+    result = client.trades.list(
+        "ETH",
+        start="2024-01-01",
+        end="2024-01-02",
+        cursor=result.next_cursor,
+        limit=1000
+    )
+    trades.extend(result.data)
+
+# Filter by side
+buys = client.trades.list("BTC", start=..., end=..., side="buy")
+
+# Async versions
+recent = await client.trades.arecent("BTC")
+result = await client.trades.alist("ETH", start=..., end=...)
 ```
 
 ### Instruments
 
 ```python
-# List all instruments
+# List all trading instruments
 instruments = client.instruments.list()
 
-# Get specific instrument
+# Get specific instrument details
 btc = client.instruments.get("BTC")
+
+# Async versions
+instruments = await client.instruments.alist()
+btc = await client.instruments.aget("BTC")
 ```
 
 ### Funding Rates
@@ -156,12 +188,16 @@ btc = client.instruments.get("BTC")
 # Get current funding rate
 current = client.funding.current("BTC")
 
-# Get funding rate history
+# Get funding rate history (start is required)
 history = client.funding.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-07"
 )
+
+# Async versions
+current = await client.funding.acurrent("BTC")
+history = await client.funding.ahistory("ETH", start=..., end=...)
 ```
 
 ### Open Interest
@@ -170,40 +206,32 @@ history = client.funding.history(
 # Get current open interest
 current = client.open_interest.current("BTC")
 
-# Get open interest history
+# Get open interest history (start is required)
 history = client.open_interest.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-07"
 )
+
+# Async versions
+current = await client.open_interest.acurrent("BTC")
+history = await client.open_interest.ahistory("ETH", start=..., end=...)
 ```
 
-## Timestamp Formats
+## WebSocket Client
 
-The SDK accepts timestamps in multiple formats:
+The WebSocket client supports three modes: real-time streaming, historical replay, and bulk streaming.
 
 ```python
-from datetime import datetime
-
-# Unix milliseconds
-client.orderbook.get("BTC", timestamp=1704067200000)
-
-# ISO string
-client.orderbook.history("BTC", start="2024-01-01", end="2024-01-02")
+import asyncio
+from oxarchive import OxArchiveWs, WsOptions
 
-# datetime object
-client.orderbook.history("BTC", start=datetime(2024, 1, 1), end=datetime(2024, 1, 2))
+ws = OxArchiveWs(WsOptions(api_key="ox_your_api_key"))
 ```
 
-## WebSocket Streaming
+### Real-time Streaming
 
-For real-time data, install with WebSocket support:
-
-```bash
-pip install oxarchive[websocket]
-```
-
-### Basic Usage
+Subscribe to live market data from Hyperliquid.
 
 ```python
 import asyncio
@@ -226,24 +254,26 @@ async def main():
     ws.subscribe_trades("BTC")
     ws.subscribe_all_tickers()
 
-    # Handle orderbook updates
+    # Handle real-time data
     ws.on_orderbook(lambda coin, data: print(f"{coin}: {data.mid_price}"))
-
-    # Handle trade updates
     ws.on_trades(lambda coin, trades: print(f"{coin}: {len(trades)} trades"))
 
     # Keep running
     await asyncio.sleep(60)
 
-    # Disconnect
+    # Unsubscribe and disconnect
+    ws.unsubscribe_orderbook("ETH")
     await ws.disconnect()
 
 asyncio.run(main())
 ```
 
-### Historical Replay (like Tardis.dev)
+### Historical Replay
 
-Replay historical data with timing preserved:
+Replay historical data with timing preserved. Perfect for backtesting.
+
+> **Important:** Replay data is delivered via `on_historical_data()`, NOT `on_trades()` or `on_orderbook()`.
+> The real-time callbacks only receive live market data from subscriptions.
 
 ```python
 import asyncio
@@ -253,13 +283,14 @@ from oxarchive import OxArchiveWs, WsOptions
 async def main():
     ws = OxArchiveWs(WsOptions(api_key="ox_..."))
 
-    # Handle replay data
+    # Handle replay data - this is where historical records arrive
     ws.on_historical_data(lambda coin, ts, data:
         print(f"{ts}: {data['mid_price']}")
     )
 
+    # Replay lifecycle events
     ws.on_replay_start(lambda ch, coin, start, end, speed:
-        print(f"Starting replay from {start} to {end} at {speed}x")
+        print(f"Starting replay: {ch}/{coin} at {speed}x")
     )
 
     ws.on_replay_complete(lambda ch, coin, sent:
@@ -272,7 +303,8 @@ async def main():
     await ws.replay(
         "orderbook", "BTC",
         start=int(time.time() * 1000) - 86400000,  # 24 hours ago
-        speed=10
+        end=int(time.time() * 1000),                # Optional
+        speed=10                                     # Optional, defaults to 1x
     )
 
     # Control playback
@@ -284,9 +316,9 @@ async def main():
 asyncio.run(main())
 ```
 
-### Bulk Streaming (like Databento)
+### Bulk Streaming
 
-Fast bulk download for data pipelines:
+Fast bulk download for data pipelines. Data arrives in batches without timing delays.
 
 ```python
 import asyncio
@@ -303,7 +335,7 @@ async def main():
     )
 
     ws.on_stream_progress(lambda snapshots_sent:
-        print(f"Sent: {snapshots_sent} snapshots")
+        print(f"Progress: {snapshots_sent} snapshots")
     )
 
     ws.on_stream_complete(lambda ch, coin, sent:
@@ -317,25 +349,25 @@ async def main():
         "orderbook", "ETH",
         start=int(time.time() * 1000) - 3600000,  # 1 hour ago
         end=int(time.time() * 1000),
-        batch_size=1000
+        batch_size=1000                            # Optional, defaults to 1000
     )
 
-    # Stop stream if needed
+    # Stop if needed
     await ws.stream_stop()
 
 asyncio.run(main())
 ```
 
-### Configuration
+### WebSocket Configuration
 
 ```python
 ws = OxArchiveWs(WsOptions(
     api_key="ox_your_api_key",
     ws_url="wss://api.0xarchive.io/ws",  # Optional
-    auto_reconnect=True,             # Auto-reconnect on disconnect
-    reconnect_delay=1.0,             # Initial reconnect delay (seconds)
-    max_reconnect_attempts=10,       # Max reconnect attempts
-    ping_interval=30.0,              # Keep-alive ping interval (seconds)
+    auto_reconnect=True,                  # Auto-reconnect on disconnect (default: True)
+    reconnect_delay=1.0,                  # Initial reconnect delay in seconds (default: 1.0)
+    max_reconnect_attempts=10,            # Max reconnect attempts (default: 10)
+    ping_interval=30.0,                   # Keep-alive ping interval in seconds (default: 30.0)
 ))
 ```
 
@@ -348,6 +380,27 @@ ws = OxArchiveWs(WsOptions(
 | `ticker` | Price and 24h volume | Yes |
 | `all_tickers` | All market tickers | No |
 
+## Timestamp Formats
+
+The SDK accepts timestamps in multiple formats:
+
+```python
+from datetime import datetime
+
+# Unix milliseconds (int)
+client.orderbook.get("BTC", timestamp=1704067200000)
+
+# ISO string
+client.orderbook.history("BTC", start="2024-01-01", end="2024-01-02")
+
+# datetime object
+client.orderbook.history(
+    "BTC",
+    start=datetime(2024, 1, 1),
+    end=datetime(2024, 1, 2)
+)
+```
+
 ## Error Handling
 
 ```python
@@ -368,12 +421,15 @@ except OxArchiveError as e:
 Full type hint support with Pydantic models:
 
 ```python
-from oxarchive import Client, OrderBook, Trade
+from oxarchive import Client
+from oxarchive.types import OrderBook, Trade, Instrument, FundingRate, OpenInterest
+from oxarchive.resources.trades import CursorResponse
 
 client = Client(api_key="ox_your_api_key")
 
 orderbook: OrderBook = client.orderbook.get("BTC")
 trades: list[Trade] = client.trades.recent("BTC")
+result: CursorResponse = client.trades.list("BTC", start=..., end=...)
 ```
 
 ## Requirements

{oxarchive-0.3.0.dist-info → oxarchive-0.3.6.dist-info}/RECORD

@@ -1,14 +1,14 @@
-oxarchive/__init__.py,sha256=QqBnxRIGEBXE2wHdmynznUEBoJsePN_xObo_v79lPZI,2181
+oxarchive/__init__.py,sha256=Q6hk0SMNM5HLYIuyFXrCPYrT261n90iPKoGakQL11vk,2181
 oxarchive/client.py,sha256=3P0fvOcyM5BWppkVV4054NduDHKvRg-cWeluoGymmRk,3163
-oxarchive/http.py,sha256=LJgw488_nNb14ixRoDv5ChuhUvyzTGtQ4aTSdEEwXww,3577
-oxarchive/types.py,sha256=8n_R41IjdNnshPscY5zAfrHa855EbvSTSdbi-GZExKo,10434
-oxarchive/websocket.py,sha256=BM6CmUbRdYptNnlicmAVPKBdqlyZBSI1l5iUt_OzWwo,25126
+oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
+oxarchive/types.py,sha256=pQJt1ZilZaV6h4anPYHloVrB97Q9Y2v9B9iYTkMXFo0,11025
+oxarchive/websocket.py,sha256=f5MeqwWL0WRn1X4uRXaSir7izUPPpkG1R75JuvA_fqE,28383
 oxarchive/resources/__init__.py,sha256=WQ4GYQ8p3L0D2Isk4IV4h1DRpvyZlt6tOF1t_CJr6ls,385
 oxarchive/resources/funding.py,sha256=TXkZxodVQTVcVbzNG6SpMQAzf8AkLm2NYZJxnP4MNXw,3500
 oxarchive/resources/instruments.py,sha256=flD1sH6x3P3CTqV1ZwkfwbranVacmhsHn5Dhr7lGQhM,1606
 oxarchive/resources/openinterest.py,sha256=h13yLA72LpfryUf8IqF6W7uE4ObYY2Qbc-auv4LtPqc,3552
 oxarchive/resources/orderbook.py,sha256=o_DTdpzKrZvHL9YXm8cGGUugPM8uUa6r9O_72r1ByV0,4557
 oxarchive/resources/trades.py,sha256=XCi2rXA2hxaTt0KNlWw8f7W0hzAvNWyT7DaivMz_rHw,10012
-oxarchive-0.3.0.dist-info/METADATA,sha256=yq_BurBDJwE1f1Nv6IANatT2KPE0uJ-7OUaY1N-omPk,8749
-oxarchive-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.3.0.dist-info/RECORD,,
+oxarchive-0.3.6.dist-info/METADATA,sha256=mAi4P9emfIG3_rlaFXyocwpRjxLEw9xo5sAwnMBUE5U,11070
+oxarchive-0.3.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.3.6.dist-info/RECORD,,