oxarchive 0.3.3__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.3
+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
@@ -45,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
@@ -97,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
 
@@ -117,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
@@ -157,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
@@ -171,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
@@ -227,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
@@ -254,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:
@@ -273,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
@@ -285,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
@@ -304,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:
@@ -318,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)
 ))
 ```
 
@@ -349,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
@@ -369,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.3 → 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.3 → oxarchive-0.3.4}/oxarchive/__init__.py

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

{oxarchive-0.3.3 → oxarchive-0.3.4}/oxarchive/types.py

@@ -118,8 +118,8 @@ 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."""

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oxarchive"
-version = "0.3.3"
+version = "0.3.4"
 description = "Official Python SDK for 0xarchive - Hyperliquid Historical Data API"
 readme = "README.md"
 license = "MIT"