oxarchive 0.4.1__tar.gz → 0.4.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.1
+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
@@ -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
@@ -449,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")
@@ -458,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.4.1 → oxarchive-0.4.4}/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
@@ -412,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")
@@ -421,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

{oxarchive-0.4.1 → oxarchive-0.4.4}/oxarchive/__init__.py

@@ -23,10 +23,12 @@ Example:
 
 from .client import Client
 from .exchanges import HyperliquidClient, LighterClient
+from .resources.orderbook import LighterGranularity
 from .types import (
     OrderBook,
     Trade,
     Instrument,
+    LighterInstrument,
     FundingRate,
     OpenInterest,
     OxArchiveError,
@@ -63,7 +65,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.4.1"
+__version__ = "0.4.4"
 
 __all__ = [
     # Client
@@ -78,6 +80,8 @@ __all__ = [
     "OrderBook",
     "Trade",
     "Instrument",
+    "LighterInstrument",
+    "LighterGranularity",
     "FundingRate",
     "OpenInterest",
     "OxArchiveError",

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

@@ -7,6 +7,7 @@ from .resources import (
     OrderBookResource,
     TradesResource,
     InstrumentsResource,
+    LighterInstrumentsResource,
     FundingResource,
     OpenInterestResource,
 )
@@ -54,6 +55,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,8 +69,8 @@ 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"""

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

@@ -2,7 +2,7 @@
 
 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
 
@@ -10,6 +10,7 @@ __all__ = [
     "OrderBookResource",
     "TradesResource",
     "InstrumentsResource",
+    "LighterInstrumentsResource",
     "FundingResource",
     "OpenInterestResource",
 ]

oxarchive-0.4.4/oxarchive/resources/instruments.py

@@ -0,0 +1,110 @@
+"""Instruments API resource."""
+
+from __future__ import annotations
+
+from ..http import HttpClient
+from ..types import Instrument, LighterInstrument
+
+
+class InstrumentsResource:
+    """
+    Instruments API resource.
+
+    Example:
+        >>> # List all instruments
+        >>> instruments = client.instruments.list()
+        >>>
+        >>> # Get specific instrument
+        >>> btc = client.instruments.get("BTC")
+    """
+
+    def __init__(self, http: HttpClient, base_path: str = "/v1"):
+        self._http = http
+        self._base_path = base_path
+
+    def list(self) -> list[Instrument]:
+        """
+        List all available trading instruments.
+
+        Returns:
+            List of instruments
+        """
+        data = self._http.get(f"{self._base_path}/instruments")
+        return [Instrument.model_validate(item) for item in data["data"]]
+
+    async def alist(self) -> list[Instrument]:
+        """Async version of list()."""
+        data = await self._http.aget(f"{self._base_path}/instruments")
+        return [Instrument.model_validate(item) for item in data["data"]]
+
+    def get(self, coin: str) -> Instrument:
+        """
+        Get a specific instrument by coin symbol.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+
+        Returns:
+            Instrument details
+        """
+        data = self._http.get(f"{self._base_path}/instruments/{coin.upper()}")
+        return Instrument.model_validate(data["data"])
+
+    async def aget(self, coin: str) -> Instrument:
+        """Async version of get()."""
+        data = await self._http.aget(f"{self._base_path}/instruments/{coin.upper()}")
+        return Instrument.model_validate(data["data"])
+
+
+class LighterInstrumentsResource:
+    """
+    Lighter.xyz Instruments API resource.
+
+    Lighter instruments have a different schema than Hyperliquid with more
+    detailed market configuration including fees and minimum amounts.
+
+    Example:
+        >>> # List all Lighter instruments
+        >>> instruments = client.lighter.instruments.list()
+        >>>
+        >>> # Get specific instrument
+        >>> btc = client.lighter.instruments.get("BTC")
+        >>> print(f"Taker fee: {btc.taker_fee}")
+    """
+
+    def __init__(self, http: HttpClient, base_path: str = "/v1/lighter"):
+        self._http = http
+        self._base_path = base_path
+
+    def list(self) -> list[LighterInstrument]:
+        """
+        List all available Lighter trading instruments.
+
+        Returns:
+            List of Lighter instruments with full market configuration
+        """
+        data = self._http.get(f"{self._base_path}/instruments")
+        return [LighterInstrument.model_validate(item) for item in data["data"]]
+
+    async def alist(self) -> list[LighterInstrument]:
+        """Async version of list()."""
+        data = await self._http.aget(f"{self._base_path}/instruments")
+        return [LighterInstrument.model_validate(item) for item in data["data"]]
+
+    def get(self, coin: str) -> LighterInstrument:
+        """
+        Get a specific Lighter instrument by coin symbol.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+
+        Returns:
+            Lighter instrument details with full market configuration
+        """
+        data = self._http.get(f"{self._base_path}/instruments/{coin.upper()}")
+        return LighterInstrument.model_validate(data["data"])
+
+    async def aget(self, coin: str) -> LighterInstrument:
+        """Async version of get()."""
+        data = await self._http.aget(f"{self._base_path}/instruments/{coin.upper()}")
+        return LighterInstrument.model_validate(data["data"])

{oxarchive-0.4.1 → oxarchive-0.4.4}/oxarchive/resources/orderbook.py

@@ -6,8 +6,13 @@ from datetime import datetime
 from typing import Optional, Union
 
 from ..http import HttpClient
+from typing import Literal
+
 from ..types import CursorResponse, OrderBook, Timestamp
 
+# Lighter orderbook granularity levels (Lighter.xyz only)
+LighterGranularity = Literal["checkpoint", "30s", "10s", "1s", "tick"]
+
 
 class OrderBookResource:
     """
@@ -101,6 +106,7 @@ class OrderBookResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         depth: Optional[int] = None,
+        granularity: Optional[LighterGranularity] = None,
     ) -> CursorResponse[list[OrderBook]]:
         """
         Get historical order book snapshots with cursor-based pagination.
@@ -112,6 +118,9 @@ class OrderBookResource:
             cursor: Cursor from previous response's next_cursor (timestamp)
             limit: Maximum number of results (default: 100, max: 1000)
             depth: Number of price levels per side
+            granularity: Data resolution for Lighter orderbook (Lighter.xyz only, ignored for Hyperliquid).
+                Options: 'checkpoint' (1min, default), '30s', '10s', '1s', 'tick'.
+                Tier restrictions apply. Credit multipliers: checkpoint=1x, 30s=2x, 10s=3x, 1s=10x, tick=20x.
 
         Returns:
             CursorResponse with order book snapshots and next_cursor for pagination
@@ -124,6 +133,11 @@ class OrderBookResource:
             ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
             ...     )
             ...     snapshots.extend(result.data)
+            >>>
+            >>> # Lighter.xyz with 10s granularity (Build+ tier)
+            >>> result = client.lighter.orderbook.history(
+            ...     "BTC", start=start, end=end, granularity="10s"
+            ... )
         """
         data = self._http.get(
             f"{self._base_path}/orderbook/{coin.upper()}/history",
@@ -133,6 +147,7 @@ class OrderBookResource:
                 "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
                 "depth": depth,
+                "granularity": granularity,
             },
         )
         return CursorResponse(
@@ -149,8 +164,9 @@ class OrderBookResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         depth: Optional[int] = None,
+        granularity: Optional[LighterGranularity] = None,
     ) -> CursorResponse[list[OrderBook]]:
-        """Async version of history(). start and end are required."""
+        """Async version of history(). start and end are required. See history() for granularity details."""
         data = await self._http.aget(
             f"{self._base_path}/orderbook/{coin.upper()}/history",
             params={
@@ -159,6 +175,7 @@ class OrderBookResource:
                 "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
                 "depth": depth,
+                "granularity": granularity,
             },
         )
         return CursorResponse(

{oxarchive-0.4.1 → oxarchive-0.4.4}/oxarchive/types.py

@@ -140,7 +140,7 @@ class Trade(BaseModel):
 
 
 class Instrument(BaseModel):
-    """Trading instrument specification."""
+    """Trading instrument specification (Hyperliquid)."""
 
     model_config = {"populate_by_name": True}
 
@@ -163,6 +163,53 @@ class Instrument(BaseModel):
     """Whether the instrument is currently tradeable."""
 
 
+class LighterInstrument(BaseModel):
+    """Trading instrument specification (Lighter.xyz).
+
+    Lighter instruments have a different schema than Hyperliquid with more
+    detailed market configuration including fees and minimum amounts.
+    """
+
+    symbol: str
+    """Instrument symbol (e.g., BTC, ETH)."""
+
+    market_id: int
+    """Unique market identifier."""
+
+    market_type: str
+    """Market type (e.g., 'perp')."""
+
+    status: str
+    """Market status (e.g., 'active')."""
+
+    taker_fee: float
+    """Taker fee rate (e.g., 0.0005 = 0.05%)."""
+
+    maker_fee: float
+    """Maker fee rate (e.g., 0.0002 = 0.02%)."""
+
+    liquidation_fee: float
+    """Liquidation fee rate."""
+
+    min_base_amount: float
+    """Minimum order size in base currency."""
+
+    min_quote_amount: float
+    """Minimum order size in quote currency."""
+
+    size_decimals: int
+    """Size decimal precision."""
+
+    price_decimals: int
+    """Price decimal precision."""
+
+    quote_decimals: int
+    """Quote currency decimal precision."""
+
+    is_active: bool
+    """Whether the instrument is currently tradeable."""
+
+
 # =============================================================================
 # Funding Types
 # =============================================================================

{oxarchive-0.4.1 → oxarchive-0.4.4}/pyproject.toml

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

oxarchive-0.4.1/oxarchive/resources/instruments.py

@@ -1,56 +0,0 @@
-"""Instruments API resource."""
-
-from __future__ import annotations
-
-from ..http import HttpClient
-from ..types import Instrument
-
-
-class InstrumentsResource:
-    """
-    Instruments API resource.
-
-    Example:
-        >>> # List all instruments
-        >>> instruments = client.instruments.list()
-        >>>
-        >>> # Get specific instrument
-        >>> btc = client.instruments.get("BTC")
-    """
-
-    def __init__(self, http: HttpClient, base_path: str = "/v1"):
-        self._http = http
-        self._base_path = base_path
-
-    def list(self) -> list[Instrument]:
-        """
-        List all available trading instruments.
-
-        Returns:
-            List of instruments
-        """
-        data = self._http.get(f"{self._base_path}/instruments")
-        return [Instrument.model_validate(item) for item in data["data"]]
-
-    async def alist(self) -> list[Instrument]:
-        """Async version of list()."""
-        data = await self._http.aget(f"{self._base_path}/instruments")
-        return [Instrument.model_validate(item) for item in data["data"]]
-
-    def get(self, coin: str) -> Instrument:
-        """
-        Get a specific instrument by coin symbol.
-
-        Args:
-            coin: The coin symbol (e.g., 'BTC', 'ETH')
-
-        Returns:
-            Instrument details
-        """
-        data = self._http.get(f"{self._base_path}/instruments/{coin.upper()}")
-        return Instrument.model_validate(data["data"])
-
-    async def aget(self, coin: str) -> Instrument:
-        """Async version of get()."""
-        data = await self._http.aget(f"{self._base_path}/instruments/{coin.upper()}")
-        return Instrument.model_validate(data["data"])