oxarchive 0.3.8__tar.gz → 0.4.4__tar.gz

{oxarchive-0.3.8 → oxarchive-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.8
+Version: 0.4.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
@@ -24,7 +24,7 @@ Requires-Python: >=3.9
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
 Provides-Extra: all
-Requires-Dist: websockets>=12.0; extra == 'all'
+Requires-Dist: websockets>=14.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.9.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
@@ -32,12 +32,16 @@ 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
-Requires-Dist: websockets>=12.0; extra == 'websocket'
+Requires-Dist: websockets>=14.0; extra == 'websocket'
 Description-Content-Type: text/markdown
 
 # oxarchive
 
-Official Python SDK for [0xarchive](https://0xarchive.io) - Hyperliquid Historical Data API.
+Official Python SDK for [0xarchive](https://0xarchive.io) - Historical Market Data API.
+
+Supports multiple exchanges:
+- **Hyperliquid** - Perpetuals data from April 2023
+- **Lighter.xyz** - Perpetuals data (August 2025+ for fills, Jan 2026+ for OB, OI, Funding Rate)
 
 ## Installation
 
@@ -58,12 +62,16 @@ from oxarchive import Client
 
 client = Client(api_key="ox_your_api_key")
 
-# Get current order book
-orderbook = client.orderbook.get("BTC")
-print(f"BTC mid price: {orderbook.mid_price}")
+# Hyperliquid data
+hl_orderbook = client.hyperliquid.orderbook.get("BTC")
+print(f"Hyperliquid BTC mid price: {hl_orderbook.mid_price}")
+
+# Lighter.xyz data
+lighter_orderbook = client.lighter.orderbook.get("BTC")
+print(f"Lighter BTC mid price: {lighter_orderbook.mid_price}")
 
 # Get historical order book snapshots
-history = client.orderbook.history(
+history = client.hyperliquid.orderbook.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-02",
@@ -82,10 +90,13 @@ from oxarchive import Client
 async def main():
     client = Client(api_key="ox_your_api_key")
 
-    # Async get
-    orderbook = await client.orderbook.aget("BTC")
+    # Async get (Hyperliquid)
+    orderbook = await client.hyperliquid.orderbook.aget("BTC")
     print(f"BTC mid price: {orderbook.mid_price}")
 
+    # Async get (Lighter.xyz)
+    lighter_ob = await client.lighter.orderbook.aget("BTC")
+
     # Don't forget to close the client
     await client.aclose()
 
@@ -96,7 +107,7 @@ Or use as async context manager:
 
 ```python
 async with Client(api_key="ox_your_api_key") as client:
-    orderbook = await client.orderbook.aget("BTC")
+    orderbook = await client.hyperliquid.orderbook.aget("BTC")
 ```
 
 ## Configuration
@@ -111,20 +122,25 @@ client = Client(
 
 ## REST API Reference
 
+All examples use `client.hyperliquid.*` but the same methods are available on `client.lighter.*` for Lighter.xyz data.
+
 ### Order Book
 
 ```python
-# Get current order book
-orderbook = client.orderbook.get("BTC")
+# Get current order book (Hyperliquid)
+orderbook = client.hyperliquid.orderbook.get("BTC")
+
+# Get current order book (Lighter.xyz)
+orderbook = client.lighter.orderbook.get("BTC")
 
 # Get order book at specific timestamp
-historical = client.orderbook.get("BTC", timestamp=1704067200000)
+historical = client.hyperliquid.orderbook.get("BTC", timestamp=1704067200000)
 
 # Get with limited depth
-shallow = client.orderbook.get("BTC", depth=10)
+shallow = client.hyperliquid.orderbook.get("BTC", depth=10)
 
 # Get historical snapshots (start and end are required)
-history = client.orderbook.history(
+history = client.hyperliquid.orderbook.history(
     "BTC",
     start="2024-01-01",
     end="2024-01-02",
@@ -133,25 +149,78 @@ history = client.orderbook.history(
 )
 
 # Async versions
-orderbook = await client.orderbook.aget("BTC")
-history = await client.orderbook.ahistory("BTC", start=..., end=...)
+orderbook = await client.hyperliquid.orderbook.aget("BTC")
+history = await client.hyperliquid.orderbook.ahistory("BTC", start=..., end=...)
+```
+
+#### Orderbook Depth Limits
+
+The `depth` parameter controls how many price levels are returned per side. Tier-based limits apply:
+
+| Tier | Max Depth |
+|------|-----------|
+| Free | 20 |
+| Build | 50 |
+| Pro | 100 |
+| Enterprise | Full Depth |
+
+**Note:** Hyperliquid source data only contains 20 levels. Higher limits apply to Lighter.xyz data.
+
+#### Lighter Orderbook Granularity
+
+Lighter.xyz orderbook history supports a `granularity` parameter for different data resolutions. Tier restrictions apply.
+
+| Granularity | Interval | Tier Required | Credit Multiplier |
+|-------------|----------|---------------|-------------------|
+| `checkpoint` | ~60s | Free+ | 1x |
+| `30s` | 30s | Build+ | 2x |
+| `10s` | 10s | Build+ | 3x |
+| `1s` | 1s | Pro+ | 10x |
+| `tick` | tick-level | Enterprise | 20x |
+
+```python
+# Get Lighter orderbook history with 10s resolution (Build+ tier)
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="10s"
+)
+
+# Get 1-second resolution (Pro+ tier)
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="1s"
+)
+
+# Tick-level data (Enterprise tier) - returns checkpoint + raw deltas
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="tick"
+)
 ```
 
+**Note:** The `granularity` parameter is ignored for Hyperliquid orderbook history.
+
 ### 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)
+recent = client.hyperliquid.trades.recent("BTC", limit=100)
 
 # Get trade history with cursor-based pagination
-result = client.trades.list("ETH", start="2024-01-01", end="2024-01-02", limit=1000)
+result = client.hyperliquid.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(
+    result = client.hyperliquid.trades.list(
         "ETH",
         start="2024-01-01",
         end="2024-01-02",
@@ -161,61 +230,103 @@ while result.next_cursor:
     trades.extend(result.data)
 
 # Filter by side
-buys = client.trades.list("BTC", start=..., end=..., side="buy")
+buys = client.hyperliquid.trades.list("BTC", start=..., end=..., side="buy")
 
 # Async versions
-recent = await client.trades.arecent("BTC")
-result = await client.trades.alist("ETH", start=..., end=...)
+recent = await client.hyperliquid.trades.arecent("BTC")
+result = await client.hyperliquid.trades.alist("ETH", start=..., end=...)
 ```
 
 ### Instruments
 
 ```python
-# List all trading instruments
-instruments = client.instruments.list()
+# List all trading instruments (Hyperliquid)
+instruments = client.hyperliquid.instruments.list()
 
 # Get specific instrument details
-btc = client.instruments.get("BTC")
+btc = client.hyperliquid.instruments.get("BTC")
+print(f"BTC size decimals: {btc.sz_decimals}")
 
 # Async versions
-instruments = await client.instruments.alist()
-btc = await client.instruments.aget("BTC")
+instruments = await client.hyperliquid.instruments.alist()
+btc = await client.hyperliquid.instruments.aget("BTC")
 ```
 
+#### Lighter.xyz Instruments
+
+Lighter instruments have a different schema with additional fields for fees, market IDs, and minimum order amounts:
+
+```python
+# List Lighter instruments (returns LighterInstrument, not Instrument)
+lighter_instruments = client.lighter.instruments.list()
+
+# Get specific Lighter instrument
+eth = client.lighter.instruments.get("ETH")
+print(f"ETH taker fee: {eth.taker_fee}")
+print(f"ETH maker fee: {eth.maker_fee}")
+print(f"ETH market ID: {eth.market_id}")
+print(f"ETH min base amount: {eth.min_base_amount}")
+
+# Async versions
+lighter_instruments = await client.lighter.instruments.alist()
+eth = await client.lighter.instruments.aget("ETH")
+```
+
+**Key differences:**
+| Field | Hyperliquid (`Instrument`) | Lighter (`LighterInstrument`) |
+|-------|---------------------------|------------------------------|
+| Symbol | `name` | `symbol` |
+| Size decimals | `sz_decimals` | `size_decimals` |
+| Fee info | Not available | `taker_fee`, `maker_fee`, `liquidation_fee` |
+| Market ID | Not available | `market_id` |
+| Min amounts | Not available | `min_base_amount`, `min_quote_amount` |
+
 ### Funding Rates
 
 ```python
 # Get current funding rate
-current = client.funding.current("BTC")
+current = client.hyperliquid.funding.current("BTC")
 
 # Get funding rate history (start is required)
-history = client.funding.history(
+history = client.hyperliquid.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=...)
+current = await client.hyperliquid.funding.acurrent("BTC")
+history = await client.hyperliquid.funding.ahistory("ETH", start=..., end=...)
 ```
 
 ### Open Interest
 
 ```python
 # Get current open interest
-current = client.open_interest.current("BTC")
+current = client.hyperliquid.open_interest.current("BTC")
 
 # Get open interest history (start is required)
-history = client.open_interest.history(
+history = client.hyperliquid.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=...)
+current = await client.hyperliquid.open_interest.acurrent("BTC")
+history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
+```
+
+### Legacy API (Deprecated)
+
+The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
+
+```python
+# Deprecated - use client.hyperliquid.orderbook.get() instead
+orderbook = client.orderbook.get("BTC")
+
+# Deprecated - use client.hyperliquid.trades.list() instead
+trades = client.trades.list("BTC", start=..., end=...)
 ```
 
 ## WebSocket Client
@@ -421,8 +532,8 @@ except OxArchiveError as e:
 Full type hint support with Pydantic models:
 
 ```python
-from oxarchive import Client
-from oxarchive.types import OrderBook, Trade, Instrument, FundingRate, OpenInterest
+from oxarchive import Client, LighterGranularity
+from oxarchive.types import OrderBook, Trade, Instrument, LighterInstrument, FundingRate, OpenInterest
 from oxarchive.resources.trades import CursorResponse
 
 client = Client(api_key="ox_your_api_key")
@@ -430,6 +541,9 @@ 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=...)
+
+# Lighter granularity type hint
+granularity: LighterGranularity = "10s"
 ```
 
 ## Requirements

{oxarchive-0.3.8 → oxarchive-0.4.4}/README.md

@@ -1,6 +1,10 @@
 # oxarchive
 
-Official Python SDK for [0xarchive](https://0xarchive.io) - Hyperliquid Historical Data API.
+Official Python SDK for [0xarchive](https://0xarchive.io) - Historical Market Data API.
+
+Supports multiple exchanges:
+- **Hyperliquid** - Perpetuals data from April 2023
+- **Lighter.xyz** - Perpetuals data (August 2025+ for fills, Jan 2026+ for OB, OI, Funding Rate)
 
 ## Installation
 
@@ -21,12 +25,16 @@ from oxarchive import Client
 
 client = Client(api_key="ox_your_api_key")
 
-# Get current order book
-orderbook = client.orderbook.get("BTC")
-print(f"BTC mid price: {orderbook.mid_price}")
+# Hyperliquid data
+hl_orderbook = client.hyperliquid.orderbook.get("BTC")
+print(f"Hyperliquid BTC mid price: {hl_orderbook.mid_price}")
+
+# Lighter.xyz data
+lighter_orderbook = client.lighter.orderbook.get("BTC")
+print(f"Lighter BTC mid price: {lighter_orderbook.mid_price}")
 
 # Get historical order book snapshots
-history = client.orderbook.history(
+history = client.hyperliquid.orderbook.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-02",
@@ -45,10 +53,13 @@ from oxarchive import Client
 async def main():
     client = Client(api_key="ox_your_api_key")
 
-    # Async get
-    orderbook = await client.orderbook.aget("BTC")
+    # Async get (Hyperliquid)
+    orderbook = await client.hyperliquid.orderbook.aget("BTC")
     print(f"BTC mid price: {orderbook.mid_price}")
 
+    # Async get (Lighter.xyz)
+    lighter_ob = await client.lighter.orderbook.aget("BTC")
+
     # Don't forget to close the client
     await client.aclose()
 
@@ -59,7 +70,7 @@ Or use as async context manager:
 
 ```python
 async with Client(api_key="ox_your_api_key") as client:
-    orderbook = await client.orderbook.aget("BTC")
+    orderbook = await client.hyperliquid.orderbook.aget("BTC")
 ```
 
 ## Configuration
@@ -74,20 +85,25 @@ client = Client(
 
 ## REST API Reference
 
+All examples use `client.hyperliquid.*` but the same methods are available on `client.lighter.*` for Lighter.xyz data.
+
 ### Order Book
 
 ```python
-# Get current order book
-orderbook = client.orderbook.get("BTC")
+# Get current order book (Hyperliquid)
+orderbook = client.hyperliquid.orderbook.get("BTC")
+
+# Get current order book (Lighter.xyz)
+orderbook = client.lighter.orderbook.get("BTC")
 
 # Get order book at specific timestamp
-historical = client.orderbook.get("BTC", timestamp=1704067200000)
+historical = client.hyperliquid.orderbook.get("BTC", timestamp=1704067200000)
 
 # Get with limited depth
-shallow = client.orderbook.get("BTC", depth=10)
+shallow = client.hyperliquid.orderbook.get("BTC", depth=10)
 
 # Get historical snapshots (start and end are required)
-history = client.orderbook.history(
+history = client.hyperliquid.orderbook.history(
     "BTC",
     start="2024-01-01",
     end="2024-01-02",
@@ -96,25 +112,78 @@ history = client.orderbook.history(
 )
 
 # Async versions
-orderbook = await client.orderbook.aget("BTC")
-history = await client.orderbook.ahistory("BTC", start=..., end=...)
+orderbook = await client.hyperliquid.orderbook.aget("BTC")
+history = await client.hyperliquid.orderbook.ahistory("BTC", start=..., end=...)
+```
+
+#### Orderbook Depth Limits
+
+The `depth` parameter controls how many price levels are returned per side. Tier-based limits apply:
+
+| Tier | Max Depth |
+|------|-----------|
+| Free | 20 |
+| Build | 50 |
+| Pro | 100 |
+| Enterprise | Full Depth |
+
+**Note:** Hyperliquid source data only contains 20 levels. Higher limits apply to Lighter.xyz data.
+
+#### Lighter Orderbook Granularity
+
+Lighter.xyz orderbook history supports a `granularity` parameter for different data resolutions. Tier restrictions apply.
+
+| Granularity | Interval | Tier Required | Credit Multiplier |
+|-------------|----------|---------------|-------------------|
+| `checkpoint` | ~60s | Free+ | 1x |
+| `30s` | 30s | Build+ | 2x |
+| `10s` | 10s | Build+ | 3x |
+| `1s` | 1s | Pro+ | 10x |
+| `tick` | tick-level | Enterprise | 20x |
+
+```python
+# Get Lighter orderbook history with 10s resolution (Build+ tier)
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="10s"
+)
+
+# Get 1-second resolution (Pro+ tier)
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="1s"
+)
+
+# Tick-level data (Enterprise tier) - returns checkpoint + raw deltas
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="tick"
+)
 ```
 
+**Note:** The `granularity` parameter is ignored for Hyperliquid orderbook history.
+
 ### 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)
+recent = client.hyperliquid.trades.recent("BTC", limit=100)
 
 # Get trade history with cursor-based pagination
-result = client.trades.list("ETH", start="2024-01-01", end="2024-01-02", limit=1000)
+result = client.hyperliquid.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(
+    result = client.hyperliquid.trades.list(
         "ETH",
         start="2024-01-01",
         end="2024-01-02",
@@ -124,61 +193,103 @@ while result.next_cursor:
     trades.extend(result.data)
 
 # Filter by side
-buys = client.trades.list("BTC", start=..., end=..., side="buy")
+buys = client.hyperliquid.trades.list("BTC", start=..., end=..., side="buy")
 
 # Async versions
-recent = await client.trades.arecent("BTC")
-result = await client.trades.alist("ETH", start=..., end=...)
+recent = await client.hyperliquid.trades.arecent("BTC")
+result = await client.hyperliquid.trades.alist("ETH", start=..., end=...)
 ```
 
 ### Instruments
 
 ```python
-# List all trading instruments
-instruments = client.instruments.list()
+# List all trading instruments (Hyperliquid)
+instruments = client.hyperliquid.instruments.list()
 
 # Get specific instrument details
-btc = client.instruments.get("BTC")
+btc = client.hyperliquid.instruments.get("BTC")
+print(f"BTC size decimals: {btc.sz_decimals}")
 
 # Async versions
-instruments = await client.instruments.alist()
-btc = await client.instruments.aget("BTC")
+instruments = await client.hyperliquid.instruments.alist()
+btc = await client.hyperliquid.instruments.aget("BTC")
 ```
 
+#### Lighter.xyz Instruments
+
+Lighter instruments have a different schema with additional fields for fees, market IDs, and minimum order amounts:
+
+```python
+# List Lighter instruments (returns LighterInstrument, not Instrument)
+lighter_instruments = client.lighter.instruments.list()
+
+# Get specific Lighter instrument
+eth = client.lighter.instruments.get("ETH")
+print(f"ETH taker fee: {eth.taker_fee}")
+print(f"ETH maker fee: {eth.maker_fee}")
+print(f"ETH market ID: {eth.market_id}")
+print(f"ETH min base amount: {eth.min_base_amount}")
+
+# Async versions
+lighter_instruments = await client.lighter.instruments.alist()
+eth = await client.lighter.instruments.aget("ETH")
+```
+
+**Key differences:**
+| Field | Hyperliquid (`Instrument`) | Lighter (`LighterInstrument`) |
+|-------|---------------------------|------------------------------|
+| Symbol | `name` | `symbol` |
+| Size decimals | `sz_decimals` | `size_decimals` |
+| Fee info | Not available | `taker_fee`, `maker_fee`, `liquidation_fee` |
+| Market ID | Not available | `market_id` |
+| Min amounts | Not available | `min_base_amount`, `min_quote_amount` |
+
 ### Funding Rates
 
 ```python
 # Get current funding rate
-current = client.funding.current("BTC")
+current = client.hyperliquid.funding.current("BTC")
 
 # Get funding rate history (start is required)
-history = client.funding.history(
+history = client.hyperliquid.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=...)
+current = await client.hyperliquid.funding.acurrent("BTC")
+history = await client.hyperliquid.funding.ahistory("ETH", start=..., end=...)
 ```
 
 ### Open Interest
 
 ```python
 # Get current open interest
-current = client.open_interest.current("BTC")
+current = client.hyperliquid.open_interest.current("BTC")
 
 # Get open interest history (start is required)
-history = client.open_interest.history(
+history = client.hyperliquid.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=...)
+current = await client.hyperliquid.open_interest.acurrent("BTC")
+history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
+```
+
+### Legacy API (Deprecated)
+
+The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
+
+```python
+# Deprecated - use client.hyperliquid.orderbook.get() instead
+orderbook = client.orderbook.get("BTC")
+
+# Deprecated - use client.hyperliquid.trades.list() instead
+trades = client.trades.list("BTC", start=..., end=...)
 ```
 
 ## WebSocket Client
@@ -384,8 +495,8 @@ except OxArchiveError as e:
 Full type hint support with Pydantic models:
 
 ```python
-from oxarchive import Client
-from oxarchive.types import OrderBook, Trade, Instrument, FundingRate, OpenInterest
+from oxarchive import Client, LighterGranularity
+from oxarchive.types import OrderBook, Trade, Instrument, LighterInstrument, FundingRate, OpenInterest
 from oxarchive.resources.trades import CursorResponse
 
 client = Client(api_key="ox_your_api_key")
@@ -393,6 +504,9 @@ 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=...)
+
+# Lighter granularity type hint
+granularity: LighterGranularity = "10s"
 ```
 
 ## Requirements