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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.6
+Version: 0.4.5
 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
@@ -307,6 +418,19 @@ async def main():
         speed=10                                     # Optional, defaults to 1x
     )
 
+    # Lighter.xyz replay with granularity (tier restrictions apply)
+    await ws.replay(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 86400000,
+        speed=10,
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
+    # Handle tick-level data (granularity='tick', Enterprise tier)
+    ws.on_historical_tick_data(lambda coin, checkpoint, deltas:
+        print(f"Checkpoint: {len(checkpoint['bids'])} bids, Deltas: {len(deltas)}")
+    )
+
     # Control playback
     await ws.replay_pause()
     await ws.replay_resume()
@@ -352,6 +476,14 @@ async def main():
         batch_size=1000                            # Optional, defaults to 1000
     )
 
+    # Lighter.xyz stream with granularity (tier restrictions apply)
+    await ws.stream(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 3600000,
+        end=int(time.time() * 1000),
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
     # Stop if needed
     await ws.stream_stop()
 
@@ -421,8 +553,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 +562,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.4.5.dist-info/RECORD

@@ -0,0 +1,15 @@
+oxarchive/__init__.py,sha256=sqzliCe2bC5ecOGaijBeOyLwj1K6d8mjwrCUSVl6r2Q,2666
+oxarchive/client.py,sha256=XWQ_VEBQy3UIAnmZQ-Z_FyzXnvMA3FITwtinBOf3o-Y,4453
+oxarchive/exchanges.py,sha256=kk--Uh4g1U_tPfhJhYtZD_1zR6tJS5D-iaPnOGwWa9c,2425
+oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
+oxarchive/types.py,sha256=YHy04TYtuEmJSHDMRh_9D9MVnhnXVc2rGagc45LwPiQ,13380
+oxarchive/websocket.py,sha256=kfpi_-Bifa5l78et-QbwV9XZ6wCVDyDmK0v90H0mFfU,29888
+oxarchive/resources/__init__.py,sha256=ZGS3rLOfQFD665oJYMia_MxfTWlal7MXtx874DLG5EE,448
+oxarchive/resources/funding.py,sha256=ybMWkpoccrkdwnd6W3oHgsaor7cBcA2nkYy4CbjmHUg,4485
+oxarchive/resources/instruments.py,sha256=6q7rMdIaixXgFVXgwQsVd-YuO7RIXr1oGPT5jBsqI9A,3733
+oxarchive/resources/openinterest.py,sha256=whwo60KFNLGwvVrDmDYYc-rMZr35Fcizb5Iil-DSvD8,4553
+oxarchive/resources/orderbook.py,sha256=NzgKH45MBb2oAHyPmy6BSikaYyq0nM-8GFjur9LIRN8,6661
+oxarchive/resources/trades.py,sha256=t4iicyi1waaHzC7Q_cC-c7O4yVx1vqS4eMH8F8_5hxk,5503
+oxarchive-0.4.5.dist-info/METADATA,sha256=i0CBOXJAlThCcc_-2PQwV-Or1-SxMHNovKVPMujsmLc,15945
+oxarchive-0.4.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.4.5.dist-info/RECORD,,

oxarchive-0.3.6.dist-info/RECORD

@@ -1,14 +0,0 @@
-oxarchive/__init__.py,sha256=Q6hk0SMNM5HLYIuyFXrCPYrT261n90iPKoGakQL11vk,2181
-oxarchive/client.py,sha256=3P0fvOcyM5BWppkVV4054NduDHKvRg-cWeluoGymmRk,3163
-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.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,,