oxarchive 0.4.1__tar.gz → 0.5.2__tar.gz

{oxarchive-0.4.1 → oxarchive-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.1
+Version: 0.5.2
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -153,6 +153,59 @@ 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.
@@ -187,17 +240,47 @@ result = await client.hyperliquid.trades.alist("ETH", start=..., end=...)
 ### Instruments
 
 ```python
-# List all trading instruments
+# List all trading instruments (Hyperliquid)
 instruments = client.hyperliquid.instruments.list()
 
 # Get specific instrument details
 btc = client.hyperliquid.instruments.get("BTC")
+print(f"BTC size decimals: {btc.sz_decimals}")
 
 # Async versions
 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
@@ -234,6 +317,57 @@ current = await client.hyperliquid.open_interest.acurrent("BTC")
 history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
 ```
 
+### Candles (OHLCV)
+
+Get historical OHLCV candle data aggregated from trades.
+
+```python
+# Get candle history (start is required)
+candles = client.hyperliquid.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="1h",  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+    limit=100
+)
+
+# Iterate through candles
+for candle in candles.data:
+    print(f"{candle.timestamp}: O={candle.open} H={candle.high} L={candle.low} C={candle.close} V={candle.volume}")
+
+# Cursor-based pagination for large datasets
+result = client.hyperliquid.candles.history("BTC", start=..., end=..., interval="1m", limit=1000)
+while result.next_cursor:
+    result = client.hyperliquid.candles.history(
+        "BTC", start=..., end=..., interval="1m",
+        cursor=result.next_cursor, limit=1000
+    )
+
+# Lighter.xyz candles
+lighter_candles = client.lighter.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="15m"
+)
+
+# Async versions
+candles = await client.hyperliquid.candles.ahistory("BTC", start=..., end=..., interval="1h")
+```
+
+#### Available Intervals
+
+| Interval | Description |
+|----------|-------------|
+| `1m` | 1 minute |
+| `5m` | 5 minutes |
+| `15m` | 15 minutes |
+| `30m` | 30 minutes |
+| `1h` | 1 hour (default) |
+| `4h` | 4 hours |
+| `1d` | 1 day |
+| `1w` | 1 week |
+
 ### Legacy API (Deprecated)
 
 The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
@@ -335,6 +469,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()
@@ -380,6 +527,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()
 
@@ -401,12 +556,43 @@ ws = OxArchiveWs(WsOptions(
 
 ### Available Channels
 
-| Channel | Description | Requires Coin |
-|---------|-------------|---------------|
-| `orderbook` | L2 order book updates | Yes |
-| `trades` | Trade/fill updates | Yes |
-| `ticker` | Price and 24h volume | Yes |
-| `all_tickers` | All market tickers | No |
+| Channel | Description | Requires Coin | Historical Support |
+|---------|-------------|---------------|-------------------|
+| `orderbook` | L2 order book updates | Yes | Yes |
+| `trades` | Trade/fill updates | Yes | Yes |
+| `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
+| `ticker` | Price and 24h volume | Yes | Real-time only |
+| `all_tickers` | All market tickers | No | Real-time only |
+
+#### Candle Replay/Stream
+
+```python
+# Replay candles at 10x speed
+await ws.replay(
+    "candles", "BTC",
+    start=int(time.time() * 1000) - 86400000,
+    end=int(time.time() * 1000),
+    speed=10,
+    interval="15m"  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+)
+
+# Bulk stream candles
+await ws.stream(
+    "candles", "ETH",
+    start=int(time.time() * 1000) - 3600000,
+    end=int(time.time() * 1000),
+    batch_size=1000,
+    interval="1h"
+)
+
+# Lighter.xyz candles
+await ws.replay(
+    "lighter_candles", "BTC",
+    start=...,
+    speed=10,
+    interval="5m"
+)
+```
 
 ## Timestamp Formats
 
@@ -449,8 +635,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")
@@ -458,6 +644,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.1 → oxarchive-0.5.2}/README.md

@@ -116,6 +116,59 @@ 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.
@@ -150,17 +203,47 @@ result = await client.hyperliquid.trades.alist("ETH", start=..., end=...)
 ### Instruments
 
 ```python
-# List all trading instruments
+# List all trading instruments (Hyperliquid)
 instruments = client.hyperliquid.instruments.list()
 
 # Get specific instrument details
 btc = client.hyperliquid.instruments.get("BTC")
+print(f"BTC size decimals: {btc.sz_decimals}")
 
 # Async versions
 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
@@ -197,6 +280,57 @@ current = await client.hyperliquid.open_interest.acurrent("BTC")
 history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
 ```
 
+### Candles (OHLCV)
+
+Get historical OHLCV candle data aggregated from trades.
+
+```python
+# Get candle history (start is required)
+candles = client.hyperliquid.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="1h",  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+    limit=100
+)
+
+# Iterate through candles
+for candle in candles.data:
+    print(f"{candle.timestamp}: O={candle.open} H={candle.high} L={candle.low} C={candle.close} V={candle.volume}")
+
+# Cursor-based pagination for large datasets
+result = client.hyperliquid.candles.history("BTC", start=..., end=..., interval="1m", limit=1000)
+while result.next_cursor:
+    result = client.hyperliquid.candles.history(
+        "BTC", start=..., end=..., interval="1m",
+        cursor=result.next_cursor, limit=1000
+    )
+
+# Lighter.xyz candles
+lighter_candles = client.lighter.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="15m"
+)
+
+# Async versions
+candles = await client.hyperliquid.candles.ahistory("BTC", start=..., end=..., interval="1h")
+```
+
+#### Available Intervals
+
+| Interval | Description |
+|----------|-------------|
+| `1m` | 1 minute |
+| `5m` | 5 minutes |
+| `15m` | 15 minutes |
+| `30m` | 30 minutes |
+| `1h` | 1 hour (default) |
+| `4h` | 4 hours |
+| `1d` | 1 day |
+| `1w` | 1 week |
+
 ### Legacy API (Deprecated)
 
 The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
@@ -298,6 +432,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()
@@ -343,6 +490,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()
 
@@ -364,12 +519,43 @@ ws = OxArchiveWs(WsOptions(
 
 ### Available Channels
 
-| Channel | Description | Requires Coin |
-|---------|-------------|---------------|
-| `orderbook` | L2 order book updates | Yes |
-| `trades` | Trade/fill updates | Yes |
-| `ticker` | Price and 24h volume | Yes |
-| `all_tickers` | All market tickers | No |
+| Channel | Description | Requires Coin | Historical Support |
+|---------|-------------|---------------|-------------------|
+| `orderbook` | L2 order book updates | Yes | Yes |
+| `trades` | Trade/fill updates | Yes | Yes |
+| `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
+| `ticker` | Price and 24h volume | Yes | Real-time only |
+| `all_tickers` | All market tickers | No | Real-time only |
+
+#### Candle Replay/Stream
+
+```python
+# Replay candles at 10x speed
+await ws.replay(
+    "candles", "BTC",
+    start=int(time.time() * 1000) - 86400000,
+    end=int(time.time() * 1000),
+    speed=10,
+    interval="15m"  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+)
+
+# Bulk stream candles
+await ws.stream(
+    "candles", "ETH",
+    start=int(time.time() * 1000) - 3600000,
+    end=int(time.time() * 1000),
+    batch_size=1000,
+    interval="1h"
+)
+
+# Lighter.xyz candles
+await ws.replay(
+    "lighter_candles", "BTC",
+    start=...,
+    speed=10,
+    interval="5m"
+)
+```
 
 ## Timestamp Formats
 
@@ -412,8 +598,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")
@@ -421,6 +607,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.1 → oxarchive-0.5.2}/oxarchive/__init__.py

@@ -23,12 +23,16 @@ Example:
 
 from .client import Client
 from .exchanges import HyperliquidClient, LighterClient
+from .resources.orderbook import LighterGranularity
 from .types import (
     OrderBook,
     Trade,
     Instrument,
+    LighterInstrument,
     FundingRate,
     OpenInterest,
+    Candle,
+    CandleInterval,
     OxArchiveError,
     # WebSocket types
     WsChannel,
@@ -63,7 +67,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.4.1"
+__version__ = "0.5.2"
 
 __all__ = [
     # Client
@@ -78,8 +82,12 @@ __all__ = [
     "OrderBook",
     "Trade",
     "Instrument",
+    "LighterInstrument",
+    "LighterGranularity",
     "FundingRate",
     "OpenInterest",
+    "Candle",
+    "CandleInterval",
     "OxArchiveError",
     # WebSocket Types
     "WsChannel",

{oxarchive-0.4.1 → oxarchive-0.5.2}/oxarchive/exchanges.py

@@ -7,8 +7,11 @@ from .resources import (
     OrderBookResource,
     TradesResource,
     InstrumentsResource,
+    LighterInstrumentsResource,
     FundingResource,
     OpenInterestResource,
+    CandlesResource,
+    LiquidationsResource,
 )
 
 
@@ -43,6 +46,12 @@ class HyperliquidClient:
         self.open_interest = OpenInterestResource(http, base_path)
         """Open interest"""
 
+        self.candles = CandlesResource(http, base_path)
+        """OHLCV candle data"""
+
+        self.liquidations = LiquidationsResource(http, base_path)
+        """Liquidation events (May 2025+)"""
+
 
 class LighterClient:
     """
@@ -54,6 +63,8 @@ class LighterClient:
         >>> client = oxarchive.Client(api_key="...")
         >>> orderbook = client.lighter.orderbook.get("BTC")
         >>> trades = client.lighter.trades.list("ETH", start=..., end=...)
+        >>> instruments = client.lighter.instruments.list()
+        >>> print(f"ETH taker fee: {instruments[0].taker_fee}")
     """
 
     def __init__(self, http: HttpClient):
@@ -66,11 +77,14 @@ class LighterClient:
         self.trades = TradesResource(http, base_path)
         """Trade/fill history"""
 
-        self.instruments = InstrumentsResource(http, base_path)
-        """Trading instruments metadata"""
+        self.instruments = LighterInstrumentsResource(http, base_path)
+        """Trading instruments metadata (returns LighterInstrument with fees, min amounts, etc.)"""
 
         self.funding = FundingResource(http, base_path)
         """Funding rates"""
 
         self.open_interest = OpenInterestResource(http, base_path)
         """Open interest"""
+
+        self.candles = CandlesResource(http, base_path)
+        """OHLCV candle data"""

{oxarchive-0.4.1 → oxarchive-0.5.2}/oxarchive/resources/__init__.py

@@ -2,14 +2,19 @@
 
 from .orderbook import OrderBookResource
 from .trades import TradesResource
-from .instruments import InstrumentsResource
+from .instruments import InstrumentsResource, LighterInstrumentsResource
 from .funding import FundingResource
 from .openinterest import OpenInterestResource
+from .candles import CandlesResource
+from .liquidations import LiquidationsResource
 
 __all__ = [
     "OrderBookResource",
     "TradesResource",
     "InstrumentsResource",
+    "LighterInstrumentsResource",
     "FundingResource",
     "OpenInterestResource",
+    "CandlesResource",
+    "LiquidationsResource",
 ]