oxarchive 0.3.2__tar.gz → 0.3.4__tar.gz

oxarchive-0.3.4/.gitignore

@@ -0,0 +1,78 @@
+# Tests (internal only, not published)
+tests/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

{oxarchive-0.3.2 → oxarchive-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.2
+Version: 0.3.4
 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.2 → oxarchive-0.3.4}/README.md

@@ -8,6 +8,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
@@ -60,13 +66,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
 
@@ -80,38 +86,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
@@ -120,12 +151,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
@@ -134,40 +169,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
@@ -190,24 +217,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
@@ -217,13 +246,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:
@@ -236,7 +266,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
@@ -248,9 +279,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
@@ -267,7 +298,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:
@@ -281,25 +312,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)
 ))
 ```
 
@@ -312,6 +343,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
@@ -332,12 +384,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.2 → oxarchive-0.3.4}/oxarchive/__init__.py

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

{oxarchive-0.3.2 → oxarchive-0.3.4}/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-0.3.2 → oxarchive-0.3.4}/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)."""
 
 
 # =============================================================================

{oxarchive-0.3.2 → oxarchive-0.3.4}/oxarchive/websocket.py

@@ -123,8 +123,8 @@ StreamCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin,
 def _transform_trade(coin: str, raw: dict) -> Trade:
     """Transform raw Hyperliquid trade format to SDK Trade type.
 
-    Raw format: { coin, side, px, sz, time, hash, tid }
-    SDK format: { coin, side, price, size, timestamp, tx_hash, trade_id }
+    Raw WebSocket format: { coin, side, px, sz, time, hash, tid, users: [maker, taker] }
+    SDK format: { coin, side, price, size, timestamp, tx_hash, trade_id, maker_address, taker_address }
     """
     from datetime import datetime
 
@@ -136,6 +136,12 @@ def _transform_trade(coin: str, raw: dict) -> Trade:
     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"),
@@ -144,6 +150,10 @@ def _transform_trade(coin: str, raw: dict) -> Trade:
         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"),
     )
 
 

{oxarchive-0.3.2 → oxarchive-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oxarchive"
-version = "0.3.2"
+version = "0.3.4"
 description = "Official Python SDK for 0xarchive - Hyperliquid Historical Data API"
 readme = "README.md"
 license = "MIT"
@@ -38,6 +38,7 @@ websocket = [
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0.0",
     "ruff>=0.4.0",
     "mypy>=1.9.0",
 ]