defistream 1.0.0__py3-none-any.whl

defistream/__init__.py

@@ -0,0 +1,81 @@
+"""
+DeFiStream Python Client
+
+Official Python client for the DeFiStream API - access historical
+DeFi events from 45+ EVM networks.
+
+Example:
+    >>> from defistream import DeFiStream
+    >>> client = DeFiStream(api_key="dsk_...")
+    >>>
+    >>> # Builder pattern
+    >>> query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
+    >>> transfers = query.as_dict()
+    >>>
+    >>> # Save to file
+    >>> query.to_csv_file("transfers.csv")
+"""
+
+from .client import AsyncDeFiStream, DeFiStream
+from .exceptions import (
+    AuthenticationError,
+    DeFiStreamError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    AAVEBorrowEvent,
+    AAVEDepositEvent,
+    AAVELiquidationEvent,
+    AAVERepayEvent,
+    AAVEWithdrawEvent,
+    ERC20ApprovalEvent,
+    ERC20TransferEvent,
+    EventBase,
+    LidoDepositEvent,
+    LidoWithdrawEvent,
+    NativeTransferEvent,
+    ResponseMetadata,
+    UniswapBurnEvent,
+    UniswapMintEvent,
+    UniswapSwapEvent,
+)
+from .query import AsyncQueryBuilder, QueryBuilder
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "DeFiStream",
+    "AsyncDeFiStream",
+    # Query builders
+    "QueryBuilder",
+    "AsyncQueryBuilder",
+    # Exceptions
+    "DeFiStreamError",
+    "AuthenticationError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "ServerError",
+    # Models
+    "EventBase",
+    "ResponseMetadata",
+    "ERC20TransferEvent",
+    "ERC20ApprovalEvent",
+    "NativeTransferEvent",
+    "AAVEDepositEvent",
+    "AAVEWithdrawEvent",
+    "AAVEBorrowEvent",
+    "AAVERepayEvent",
+    "AAVELiquidationEvent",
+    "UniswapSwapEvent",
+    "UniswapMintEvent",
+    "UniswapBurnEvent",
+    "LidoDepositEvent",
+    "LidoWithdrawEvent",
+]

defistream/client.py

@@ -0,0 +1,380 @@
+"""DeFiStream API client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    DeFiStreamError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import ResponseMetadata
+from .protocols import (
+    AAVEProtocol,
+    AsyncAAVEProtocol,
+    AsyncERC20Protocol,
+    AsyncLidoProtocol,
+    AsyncNativeTokenProtocol,
+    AsyncStaderProtocol,
+    AsyncThresholdProtocol,
+    AsyncUniswapProtocol,
+    ERC20Protocol,
+    LidoProtocol,
+    NativeTokenProtocol,
+    StaderProtocol,
+    ThresholdProtocol,
+    UniswapProtocol,
+)
+
+DEFAULT_BASE_URL = "https://api.defistream.dev/v1"
+DEFAULT_TIMEOUT = 60.0
+
+
+class BaseClient:
+    """Base client with shared functionality."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ):
+        # Read API key from argument or environment
+        self.api_key = api_key or os.environ.get("DEFISTREAM_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key required. Pass api_key or set DEFISTREAM_API_KEY environment variable."
+            )
+
+        self.base_url = (base_url or os.environ.get("DEFISTREAM_BASE_URL", DEFAULT_BASE_URL)).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.last_response: ResponseMetadata = ResponseMetadata()
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get request headers."""
+        return {
+            "X-API-Key": self.api_key,  # type: ignore
+            "Accept": "application/json",
+        }
+
+    def _parse_response_metadata(self, headers: httpx.Headers) -> ResponseMetadata:
+        """Parse rate limit and quota info from response headers."""
+        return ResponseMetadata(
+            rate_limit=int(headers.get("X-RateLimit-Limit", 0)) or None,
+            quota_remaining=int(headers.get("X-RateLimit-Remaining", 0)) or None,
+            request_cost=int(headers.get("X-Request-Cost", 0)) or None,
+        )
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Handle error responses."""
+        status_code = response.status_code
+
+        try:
+            data = response.json()
+            message = data.get("error", data.get("message", response.text))
+            error_code = data.get("code", "")
+        except Exception:
+            message = response.text
+            error_code = ""
+
+        if status_code == 401:
+            raise AuthenticationError(message, status_code, response)
+
+        if status_code == 403:
+            if error_code == "quota_exceeded":
+                # Try to extract remaining quota from response
+                remaining = 0
+                try:
+                    remaining = int(data.get("remaining", 0))
+                except (ValueError, TypeError):
+                    pass
+                raise QuotaExceededError(message, remaining=remaining, status_code=status_code, response=response)
+            raise AuthenticationError(message, status_code, response)
+
+        if status_code == 404:
+            raise NotFoundError(message, status_code, response)
+
+        if status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(
+                message,
+                retry_after=float(retry_after) if retry_after else None,
+                status_code=status_code,
+                response=response,
+            )
+
+        if status_code == 400:
+            raise ValidationError(message, status_code, response)
+
+        if status_code >= 500:
+            raise ServerError(message, status_code, response)
+
+        raise DeFiStreamError(message, status_code, response)
+
+    def _process_response(
+        self,
+        response: httpx.Response,
+        as_dataframe: Literal["pandas", "polars"] | None = None,
+        output_file: str | None = None,
+    ) -> list[dict[str, Any]] | Any:
+        """Process response and optionally convert to DataFrame or save to file."""
+        self.last_response = self._parse_response_metadata(response.headers)
+
+        if response.status_code >= 400:
+            self._handle_error_response(response)
+
+        content_type = response.headers.get("Content-Type", "")
+
+        # Handle file output
+        if output_file:
+            if output_file.endswith(".parquet"):
+                with open(output_file, "wb") as f:
+                    f.write(response.content)
+            else:
+                with open(output_file, "w") as f:
+                    f.write(response.text)
+            return None
+
+        # Handle CSV response
+        if "text/csv" in content_type:
+            csv_text = response.text
+            if as_dataframe == "pandas":
+                import io
+                import pandas as pd
+                return pd.read_csv(io.StringIO(csv_text))
+            elif as_dataframe == "polars":
+                import io
+                import polars as pl
+                return pl.read_csv(io.StringIO(csv_text))
+            return csv_text
+
+        # Handle Parquet response
+        if "application/octet-stream" in content_type or "application/parquet" in content_type:
+            if as_dataframe == "pandas":
+                import io
+                import pandas as pd
+                df = pd.read_parquet(io.BytesIO(response.content))
+                if "time" in df.columns:
+                    df["time"] = pd.to_datetime(df["time"], unit="s", utc=True)
+                return df
+            elif as_dataframe == "polars":
+                import io
+                import polars as pl
+                df = pl.read_parquet(io.BytesIO(response.content))
+                if "time" in df.columns:
+                    df = df.with_columns(
+                        pl.from_epoch("time", time_unit="s").dt.replace_time_zone("UTC")
+                    )
+                return df
+            return response.content
+
+        # Handle JSON response
+        data = response.json()
+
+        if data.get("status") == "error":
+            raise DeFiStreamError(data.get("error", "Unknown error"))
+
+        events = data.get("events", [])
+
+        if as_dataframe == "pandas":
+            import pandas as pd
+            df = pd.DataFrame(events)
+            if "time" in df.columns:
+                df["time"] = pd.to_datetime(df["time"], unit="s", utc=True)
+            return df
+        elif as_dataframe == "polars":
+            import polars as pl
+            df = pl.DataFrame(events)
+            if "time" in df.columns:
+                df = df.with_columns(
+                    pl.from_epoch("time", time_unit="s").dt.replace_time_zone("UTC")
+                )
+            return df
+
+        return events
+
+
+class DeFiStream(BaseClient):
+    """
+    Synchronous DeFiStream API client with builder pattern.
+
+    Example:
+        >>> from defistream import DeFiStream
+        >>> client = DeFiStream(api_key="dsk_...")
+        >>>
+        >>> # Builder pattern
+        >>> query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
+        >>> df = query.as_pandas()
+        >>>
+        >>> # Or chain everything
+        >>> transfers = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000).as_dict()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http_client: httpx.Client | None = None
+
+        # Protocol clients
+        self.erc20 = ERC20Protocol(self)
+        self.native_token = NativeTokenProtocol(self)
+        self.aave = AAVEProtocol(self)
+        self.uniswap = UniswapProtocol(self)
+        self.lido = LidoProtocol(self)
+        self.stader = StaderProtocol(self)
+        self.threshold = ThresholdProtocol(self)
+
+    @property
+    def _client(self) -> httpx.Client:
+        """Lazy-initialize HTTP client."""
+        if self._http_client is None:
+            self._http_client = httpx.Client(
+                base_url=self.base_url,
+                headers=self._get_headers(),
+                timeout=self.timeout,
+            )
+        return self._http_client
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        if self._http_client is not None:
+            self._http_client.close()
+            self._http_client = None
+
+    def __enter__(self) -> "DeFiStream":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        as_dataframe: Literal["pandas", "polars"] | None = None,
+        output_file: str | None = None,
+    ) -> list[dict[str, Any]] | Any:
+        """Make HTTP request."""
+        if params is None:
+            params = {}
+
+        if output_file:
+            if output_file.endswith(".parquet"):
+                params["format"] = "parquet"
+            elif output_file.endswith(".csv"):
+                params["format"] = "csv"
+
+        response = self._client.request(method, path, params=params)
+        return self._process_response(response, as_dataframe, output_file)
+
+    def decoders(self) -> list[str]:
+        """Get list of available decoders."""
+        response = self._client.get("/decoders")
+        if response.status_code >= 400:
+            self._handle_error_response(response)
+        data = response.json()
+        return data.get("decoders", [])
+
+
+class AsyncDeFiStream(BaseClient):
+    """
+    Asynchronous DeFiStream API client with builder pattern.
+
+    Example:
+        >>> import asyncio
+        >>> from defistream import AsyncDeFiStream
+        >>>
+        >>> async def main():
+        ...     async with AsyncDeFiStream(api_key="dsk_...") as client:
+        ...         query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
+        ...         df = await query.as_pandas()
+        ...
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http_client: httpx.AsyncClient | None = None
+
+        # Protocol clients (async versions)
+        self.erc20 = AsyncERC20Protocol(self)
+        self.native_token = AsyncNativeTokenProtocol(self)
+        self.aave = AsyncAAVEProtocol(self)
+        self.uniswap = AsyncUniswapProtocol(self)
+        self.lido = AsyncLidoProtocol(self)
+        self.stader = AsyncStaderProtocol(self)
+        self.threshold = AsyncThresholdProtocol(self)
+
+    @property
+    def _client(self) -> httpx.AsyncClient:
+        """Lazy-initialize async HTTP client."""
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self._get_headers(),
+                timeout=self.timeout,
+            )
+        return self._http_client
+
+    async def close(self) -> None:
+        """Close the async HTTP client."""
+        if self._http_client is not None:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    async def __aenter__(self) -> "AsyncDeFiStream":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        as_dataframe: Literal["pandas", "polars"] | None = None,
+        output_file: str | None = None,
+    ) -> list[dict[str, Any]] | Any:
+        """Make async HTTP request."""
+        if params is None:
+            params = {}
+
+        if output_file:
+            if output_file.endswith(".parquet"):
+                params["format"] = "parquet"
+            elif output_file.endswith(".csv"):
+                params["format"] = "csv"
+
+        response = await self._client.request(method, path, params=params)
+        return self._process_response(response, as_dataframe, output_file)
+
+    async def decoders(self) -> list[str]:
+        """Get list of available decoders."""
+        response = await self._client.get("/decoders")
+        if response.status_code >= 400:
+            self._handle_error_response(response)
+        data = response.json()
+        return data.get("decoders", [])

defistream/exceptions.py

@@ -0,0 +1,65 @@
+"""DeFiStream API exceptions."""
+
+from typing import Any
+
+
+class DeFiStreamError(Exception):
+    """Base exception for DeFiStream API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, response: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthenticationError(DeFiStreamError):
+    """Raised when API key is invalid or missing."""
+
+    pass
+
+
+class QuotaExceededError(DeFiStreamError):
+    """Raised when account quota is exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        remaining: int = 0,
+        status_code: int | None = None,
+        response: Any = None,
+    ):
+        super().__init__(message, status_code, response)
+        self.remaining = remaining
+
+
+class RateLimitError(DeFiStreamError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: float | None = None,
+        status_code: int | None = None,
+        response: Any = None,
+    ):
+        super().__init__(message, status_code, response)
+        self.retry_after = retry_after
+
+
+class ValidationError(DeFiStreamError):
+    """Raised when request parameters are invalid."""
+
+    pass
+
+
+class NotFoundError(DeFiStreamError):
+    """Raised when a resource is not found."""
+
+    pass
+
+
+class ServerError(DeFiStreamError):
+    """Raised when the server returns a 5xx error."""
+
+    pass

defistream/models.py

@@ -0,0 +1,174 @@
+"""Pydantic models for DeFiStream API responses."""
+
+from typing import Any, Literal
+from pydantic import BaseModel, Field
+
+
+class ResponseMetadata(BaseModel):
+    """Metadata from API response headers."""
+
+    rate_limit: int | None = None
+    quota_remaining: int | None = None
+    request_cost: int | None = None
+
+
+class EventBase(BaseModel):
+    """Base model for all events."""
+
+    block_number: int
+    time: str | None = None
+    # Verbose fields (only present when verbose=true)
+    name: str | None = None
+    network: str | None = None
+    tx_id: str | None = None
+    tx_hash: str | None = None
+    log_index: int | None = None
+
+
+class ERC20TransferEvent(EventBase):
+    """ERC20 Transfer event."""
+
+    sender: str = Field(alias="from_address", default="")
+    receiver: str = Field(alias="to_address", default="")
+    amount: float = 0.0
+    token_address: str | None = None
+    token_symbol: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class ERC20ApprovalEvent(EventBase):
+    """ERC20 Approval event."""
+
+    owner: str = ""
+    spender: str = ""
+    amount: float = 0.0
+    token_address: str | None = None
+    token_symbol: str | None = None
+
+
+class NativeTransferEvent(EventBase):
+    """Native token (ETH/MATIC/etc) transfer event."""
+
+    sender: str = ""
+    receiver: str = ""
+    amount: float = 0.0
+
+
+class AAVEDepositEvent(EventBase):
+    """AAVE V3 Supply/Deposit event."""
+
+    user: str = ""
+    reserve: str = ""
+    amount: float = 0.0
+    on_behalf_of: str | None = None
+
+
+class AAVEWithdrawEvent(EventBase):
+    """AAVE V3 Withdraw event."""
+
+    user: str = ""
+    reserve: str = ""
+    amount: float = 0.0
+    to: str | None = None
+
+
+class AAVEBorrowEvent(EventBase):
+    """AAVE V3 Borrow event."""
+
+    user: str = ""
+    reserve: str = ""
+    amount: float = 0.0
+    interest_rate_mode: int | None = None
+    borrow_rate: float | None = None
+    on_behalf_of: str | None = None
+
+
+class AAVERepayEvent(EventBase):
+    """AAVE V3 Repay event."""
+
+    user: str = ""
+    reserve: str = ""
+    amount: float = 0.0
+    repayer: str | None = None
+    use_a_tokens: bool | None = None
+
+
+class AAVELiquidationEvent(EventBase):
+    """AAVE V3 Liquidation event."""
+
+    liquidator: str = ""
+    user: str = ""
+    collateral_asset: str = ""
+    debt_asset: str = ""
+    debt_to_cover: float = 0.0
+    liquidated_collateral_amount: float = 0.0
+    receive_a_token: bool | None = None
+
+
+class UniswapSwapEvent(EventBase):
+    """Uniswap V3 Swap event."""
+
+    pool: str = ""
+    sender: str = ""
+    recipient: str = ""
+    amount0: float = 0.0
+    amount1: float = 0.0
+    sqrt_price_x96: int | None = None
+    liquidity: int | None = None
+    tick: int | None = None
+
+
+class UniswapMintEvent(EventBase):
+    """Uniswap V3 Mint (add liquidity) event."""
+
+    pool: str = ""
+    owner: str = ""
+    tick_lower: int = 0
+    tick_upper: int = 0
+    amount: int = 0
+    amount0: float = 0.0
+    amount1: float = 0.0
+
+
+class UniswapBurnEvent(EventBase):
+    """Uniswap V3 Burn (remove liquidity) event."""
+
+    pool: str = ""
+    owner: str = ""
+    tick_lower: int = 0
+    tick_upper: int = 0
+    amount: int = 0
+    amount0: float = 0.0
+    amount1: float = 0.0
+
+
+class LidoDepositEvent(EventBase):
+    """Lido stETH deposit event."""
+
+    sender: str = ""
+    amount: float = 0.0
+    shares: float = 0.0
+
+
+class LidoWithdrawEvent(EventBase):
+    """Lido stETH withdrawal event."""
+
+    owner: str = ""
+    request_id: int = 0
+    amount: float = 0.0
+
+
+class EventsResponse(BaseModel):
+    """Standard events API response."""
+
+    status: Literal["success", "error"]
+    events: list[dict[str, Any]] = []
+    count: int = 0
+    error: str | None = None
+
+
+class DecodersResponse(BaseModel):
+    """Response from /decoders endpoint."""
+
+    decoders: list[str] = []