defistream 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

defistream/__init__.py

@@ -1,19 +1,22 @@
 """
 DeFiStream Python Client
 
-Official Python client for the DeFiStream API - access historical
-DeFi events from 45+ EVM networks.
+Official Python client for the DeFiStream API.
 
 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()
+    >>> # Builder pattern - returns pandas DataFrame
+    >>> df = (
+    ...     client.erc20.transfers("USDT")
+    ...     .network("ETH")
+    ...     .block_range(21000000, 21010000)
+    ...     .as_df()
+    ... )
     >>>
     >>> # Save to file
-    >>> query.to_csv_file("transfers.csv")
+    >>> query.as_file("transfers.parquet")
 """
 
 from .client import AsyncDeFiStream, DeFiStream
@@ -32,20 +35,17 @@ from .models import (
     AAVELiquidationEvent,
     AAVERepayEvent,
     AAVEWithdrawEvent,
-    ERC20ApprovalEvent,
     ERC20TransferEvent,
     EventBase,
     LidoDepositEvent,
     LidoWithdrawEvent,
     NativeTransferEvent,
     ResponseMetadata,
-    UniswapBurnEvent,
-    UniswapMintEvent,
     UniswapSwapEvent,
 )
 from .query import AsyncQueryBuilder, QueryBuilder
 
-__version__ = "0.1.0"
+__version__ = "1.0.2"
 
 __all__ = [
     # Clients
@@ -66,7 +66,6 @@ __all__ = [
     "EventBase",
     "ResponseMetadata",
     "ERC20TransferEvent",
-    "ERC20ApprovalEvent",
     "NativeTransferEvent",
     "AAVEDepositEvent",
     "AAVEWithdrawEvent",
@@ -74,8 +73,6 @@ __all__ = [
     "AAVERepayEvent",
     "AAVELiquidationEvent",
     "UniswapSwapEvent",
-    "UniswapMintEvent",
-    "UniswapBurnEvent",
     "LidoDepositEvent",
     "LidoWithdrawEvent",
 ]

defistream/protocols.py

@@ -21,34 +21,25 @@ class ERC20Protocol:
         Start a query for ERC20 transfer events.
 
         Args:
-            token: Optional token symbol (USDT, USDC, WETH, etc.)
+            token: Token symbol (USDT, USDC, WETH, etc.) or contract address
 
         Returns:
             QueryBuilder for chaining filters
 
         Example:
-            query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
-            df = query.as_pandas()
+            df = (
+                client.erc20.transfers("USDT")
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .as_df()
+            )
         """
         params = {"token": token} if token else {}
         return QueryBuilder(self._client, "/erc20/events/transfer", params)
 
-    def approvals(self, token: str | None = None) -> QueryBuilder:
-        """
-        Start a query for ERC20 approval events.
-
-        Args:
-            token: Optional token symbol
-
-        Returns:
-            QueryBuilder for chaining filters
-        """
-        params = {"token": token} if token else {}
-        return QueryBuilder(self._client, "/erc20/events/approval", params)
-
 
 class NativeTokenProtocol:
-    """Native token (ETH, MATIC, BNB, etc.) events with builder pattern."""
+    """Native token (ETH, MATIC, etc.) events with builder pattern."""
 
     def __init__(self, client: "BaseClient"):
         self._client = client
@@ -61,8 +52,13 @@ class NativeTokenProtocol:
             QueryBuilder for chaining filters
 
         Example:
-            query = client.native_token.transfers().network("ETH").start_block(24000000).end_block(24100000)
-            transfers = query.min_amount(1.0).as_dict()
+            df = (
+                client.native_token.transfers()
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .min_amount(1.0)
+                .as_df()
+            )
         """
         return QueryBuilder(self._client, "/native_token/events/transfer")
 
@@ -89,6 +85,10 @@ class AAVEProtocol:
         """Start a query for AAVE repay events."""
         return QueryBuilder(self._client, "/aave/events/repay")
 
+    def flashloans(self) -> QueryBuilder:
+        """Start a query for AAVE flash loan events."""
+        return QueryBuilder(self._client, "/aave/events/flashloan")
+
     def liquidations(self) -> QueryBuilder:
         """Start a query for AAVE liquidation events."""
         return QueryBuilder(self._client, "/aave/events/liquidation")
@@ -110,16 +110,20 @@ class UniswapProtocol:
         Start a query for Uniswap V3 swap events.
 
         Args:
-            symbol0: Optional first token symbol (e.g., WETH)
-            symbol1: Optional second token symbol (e.g., USDC)
-            fee: Optional fee tier (100, 500, 3000, 10000)
+            symbol0: First token symbol (e.g., WETH)
+            symbol1: Second token symbol (e.g., USDC)
+            fee: Fee tier (100, 500, 3000, 10000)
 
         Returns:
             QueryBuilder for chaining filters
 
         Example:
-            query = client.uniswap.swaps("WETH", "USDC", 500).network("ETH").start_block(24000000).end_block(24100000)
-            df = query.as_pandas()
+            df = (
+                client.uniswap.swaps("WETH", "USDC", 500)
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .as_df()
+            )
         """
         params: dict[str, Any] = {}
         if symbol0:
@@ -130,13 +134,13 @@ class UniswapProtocol:
             params["fee"] = fee
         return QueryBuilder(self._client, "/uniswap/events/swap", params)
 
-    def mints(
+    def deposits(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> QueryBuilder:
-        """Start a query for Uniswap V3 mint (add liquidity) events."""
+        """Start a query for Uniswap V3 deposit (add liquidity) events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -144,15 +148,15 @@ class UniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return QueryBuilder(self._client, "/uniswap/events/mint", params)
+        return QueryBuilder(self._client, "/uniswap/events/deposit", params)
 
-    def burns(
+    def withdrawals(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> QueryBuilder:
-        """Start a query for Uniswap V3 burn (remove liquidity) events."""
+        """Start a query for Uniswap V3 withdrawal (remove liquidity) events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -160,7 +164,23 @@ class UniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return QueryBuilder(self._client, "/uniswap/events/burn", params)
+        return QueryBuilder(self._client, "/uniswap/events/withdraw", params)
+
+    def collects(
+        self,
+        symbol0: str | None = None,
+        symbol1: str | None = None,
+        fee: int | None = None,
+    ) -> QueryBuilder:
+        """Start a query for Uniswap V3 collect (fee collection) events."""
+        params: dict[str, Any] = {}
+        if symbol0:
+            params["symbol0"] = symbol0
+        if symbol1:
+            params["symbol1"] = symbol1
+        if fee:
+            params["fee"] = fee
+        return QueryBuilder(self._client, "/uniswap/events/collect", params)
 
 
 class LidoProtocol:
@@ -169,17 +189,31 @@ class LidoProtocol:
     def __init__(self, client: "BaseClient"):
         self._client = client
 
+    # L1 ETH events
     def deposits(self) -> QueryBuilder:
-        """Start a query for Lido stETH deposit events."""
+        """Start a query for Lido stETH deposit events (ETH L1 only)."""
         return QueryBuilder(self._client, "/lido/events/deposit")
 
-    def withdrawals(self) -> QueryBuilder:
-        """Start a query for Lido withdrawal events."""
-        return QueryBuilder(self._client, "/lido/events/withdraw")
+    def withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for Lido withdrawal request events (ETH L1 only)."""
+        return QueryBuilder(self._client, "/lido/events/withdrawal_request")
+
+    def withdrawals_claimed(self) -> QueryBuilder:
+        """Start a query for Lido claimed withdrawal events (ETH L1 only)."""
+        return QueryBuilder(self._client, "/lido/events/withdrawal_claimed")
+
+    # L2 events
+    def l2_deposits(self) -> QueryBuilder:
+        """Start a query for Lido L2 deposit events (L2 networks only)."""
+        return QueryBuilder(self._client, "/lido/events/l2_deposit")
+
+    def l2_withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for Lido L2 withdrawal request events (L2 networks only)."""
+        return QueryBuilder(self._client, "/lido/events/l2_withdrawal_request")
 
 
 class StaderProtocol:
-    """Stader EthX staking events with builder pattern."""
+    """Stader ETHx staking events with builder pattern (ETH only)."""
 
     def __init__(self, client: "BaseClient"):
         self._client = client
@@ -188,24 +222,36 @@ class StaderProtocol:
         """Start a query for Stader deposit events."""
         return QueryBuilder(self._client, "/stader/events/deposit")
 
+    def withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for Stader withdrawal request events."""
+        return QueryBuilder(self._client, "/stader/events/withdrawal_request")
+
     def withdrawals(self) -> QueryBuilder:
         """Start a query for Stader withdrawal events."""
-        return QueryBuilder(self._client, "/stader/events/withdraw")
+        return QueryBuilder(self._client, "/stader/events/withdrawal")
 
 
 class ThresholdProtocol:
-    """Threshold tBTC events with builder pattern."""
+    """Threshold tBTC events with builder pattern (ETH only)."""
 
     def __init__(self, client: "BaseClient"):
         self._client = client
 
-    def mints(self) -> QueryBuilder:
-        """Start a query for tBTC mint events."""
-        return QueryBuilder(self._client, "/threshold/events/mint")
+    def deposit_requests(self) -> QueryBuilder:
+        """Start a query for tBTC deposit request (reveal) events."""
+        return QueryBuilder(self._client, "/threshold/events/deposit_request")
 
-    def burns(self) -> QueryBuilder:
-        """Start a query for tBTC burn/redeem events."""
-        return QueryBuilder(self._client, "/threshold/events/burn")
+    def deposits(self) -> QueryBuilder:
+        """Start a query for tBTC deposit (mint) events."""
+        return QueryBuilder(self._client, "/threshold/events/deposit")
+
+    def withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for tBTC withdrawal request events."""
+        return QueryBuilder(self._client, "/threshold/events/withdrawal_request")
+
+    def withdrawals(self) -> QueryBuilder:
+        """Start a query for tBTC withdrawal (unmint) events."""
+        return QueryBuilder(self._client, "/threshold/events/withdrawal")
 
 
 # Async protocol implementations
@@ -220,11 +266,6 @@ class AsyncERC20Protocol:
         params = {"token": token} if token else {}
         return AsyncQueryBuilder(self._client, "/erc20/events/transfer", params)
 
-    def approvals(self, token: str | None = None) -> AsyncQueryBuilder:
-        """Start a query for ERC20 approval events."""
-        params = {"token": token} if token else {}
-        return AsyncQueryBuilder(self._client, "/erc20/events/approval", params)
-
 
 class AsyncNativeTokenProtocol:
     """Async native token events with builder pattern."""
@@ -259,6 +300,10 @@ class AsyncAAVEProtocol:
         """Start a query for AAVE repay events."""
         return AsyncQueryBuilder(self._client, "/aave/events/repay")
 
+    def flashloans(self) -> AsyncQueryBuilder:
+        """Start a query for AAVE flash loan events."""
+        return AsyncQueryBuilder(self._client, "/aave/events/flashloan")
+
     def liquidations(self) -> AsyncQueryBuilder:
         """Start a query for AAVE liquidation events."""
         return AsyncQueryBuilder(self._client, "/aave/events/liquidation")
@@ -286,13 +331,29 @@ class AsyncUniswapProtocol:
             params["fee"] = fee
         return AsyncQueryBuilder(self._client, "/uniswap/events/swap", params)
 
-    def mints(
+    def deposits(
+        self,
+        symbol0: str | None = None,
+        symbol1: str | None = None,
+        fee: int | None = None,
+    ) -> AsyncQueryBuilder:
+        """Start a query for Uniswap V3 deposit events."""
+        params: dict[str, Any] = {}
+        if symbol0:
+            params["symbol0"] = symbol0
+        if symbol1:
+            params["symbol1"] = symbol1
+        if fee:
+            params["fee"] = fee
+        return AsyncQueryBuilder(self._client, "/uniswap/events/deposit", params)
+
+    def withdrawals(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> AsyncQueryBuilder:
-        """Start a query for Uniswap V3 mint events."""
+        """Start a query for Uniswap V3 withdrawal events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -300,15 +361,15 @@ class AsyncUniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return AsyncQueryBuilder(self._client, "/uniswap/events/mint", params)
+        return AsyncQueryBuilder(self._client, "/uniswap/events/withdraw", params)
 
-    def burns(
+    def collects(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> AsyncQueryBuilder:
-        """Start a query for Uniswap V3 burn events."""
+        """Start a query for Uniswap V3 collect events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -316,7 +377,7 @@ class AsyncUniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return AsyncQueryBuilder(self._client, "/uniswap/events/burn", params)
+        return AsyncQueryBuilder(self._client, "/uniswap/events/collect", params)
 
 
 class AsyncLidoProtocol:
@@ -326,12 +387,24 @@ class AsyncLidoProtocol:
         self._client = client
 
     def deposits(self) -> AsyncQueryBuilder:
-        """Start a query for Lido deposit events."""
+        """Start a query for Lido deposit events (ETH L1 only)."""
         return AsyncQueryBuilder(self._client, "/lido/events/deposit")
 
-    def withdrawals(self) -> AsyncQueryBuilder:
-        """Start a query for Lido withdrawal events."""
-        return AsyncQueryBuilder(self._client, "/lido/events/withdraw")
+    def withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for Lido withdrawal request events (ETH L1 only)."""
+        return AsyncQueryBuilder(self._client, "/lido/events/withdrawal_request")
+
+    def withdrawals_claimed(self) -> AsyncQueryBuilder:
+        """Start a query for Lido claimed withdrawal events (ETH L1 only)."""
+        return AsyncQueryBuilder(self._client, "/lido/events/withdrawal_claimed")
+
+    def l2_deposits(self) -> AsyncQueryBuilder:
+        """Start a query for Lido L2 deposit events."""
+        return AsyncQueryBuilder(self._client, "/lido/events/l2_deposit")
+
+    def l2_withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for Lido L2 withdrawal request events."""
+        return AsyncQueryBuilder(self._client, "/lido/events/l2_withdrawal_request")
 
 
 class AsyncStaderProtocol:
@@ -344,9 +417,13 @@ class AsyncStaderProtocol:
         """Start a query for Stader deposit events."""
         return AsyncQueryBuilder(self._client, "/stader/events/deposit")
 
+    def withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for Stader withdrawal request events."""
+        return AsyncQueryBuilder(self._client, "/stader/events/withdrawal_request")
+
     def withdrawals(self) -> AsyncQueryBuilder:
         """Start a query for Stader withdrawal events."""
-        return AsyncQueryBuilder(self._client, "/stader/events/withdraw")
+        return AsyncQueryBuilder(self._client, "/stader/events/withdrawal")
 
 
 class AsyncThresholdProtocol:
@@ -355,10 +432,18 @@ class AsyncThresholdProtocol:
     def __init__(self, client: "BaseClient"):
         self._client = client
 
-    def mints(self) -> AsyncQueryBuilder:
-        """Start a query for tBTC mint events."""
-        return AsyncQueryBuilder(self._client, "/threshold/events/mint")
+    def deposit_requests(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC deposit request events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/deposit_request")
 
-    def burns(self) -> AsyncQueryBuilder:
-        """Start a query for tBTC burn events."""
-        return AsyncQueryBuilder(self._client, "/threshold/events/burn")
+    def deposits(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC deposit events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/deposit")
+
+    def withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC withdrawal request events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/withdrawal_request")
+
+    def withdrawals(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC withdrawal events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/withdrawal")

defistream/query.py

@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from .client import BaseClient
 
-T = TypeVar("T")
-
 
 class QueryBuilder:
     """
@@ -20,7 +18,7 @@ class QueryBuilder:
     - as_file() - saves to CSV, Parquet, or JSON file
 
     Example:
-        query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
+        query = client.erc20.transfers("USDT").network("ETH").block_range(21000000, 21010000)
         query = query.min_amount(1000).sender("0x...")
         df = query.as_df()  # pandas DataFrame
         df = query.as_df("polars")  # polars DataFrame
@@ -51,7 +49,7 @@ class QueryBuilder:
 
     # Network and block range
     def network(self, network: str) -> "QueryBuilder":
-        """Set the network (ETH, ARB, BASE, OP, etc.)."""
+        """Set the network (ETH, ARB, BASE, OP, POLYGON, etc.)."""
         return self._copy_with(network=network)
 
     def start_block(self, block: int) -> "QueryBuilder":
@@ -79,13 +77,13 @@ class QueryBuilder:
         """Set both start and end times."""
         return self._copy_with(since=start, until=end)
 
-    # Common filters
+    # ERC20 and Native Token filters
     def sender(self, address: str) -> "QueryBuilder":
-        """Filter by sender address."""
+        """Filter by sender address (ERC20, Native Token)."""
         return self._copy_with(sender=address)
 
     def receiver(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address."""
+        """Filter by receiver address (ERC20, Native Token)."""
         return self._copy_with(receiver=address)
 
     def from_address(self, address: str) -> "QueryBuilder":
@@ -97,52 +95,40 @@ class QueryBuilder:
         return self.receiver(address)
 
     def min_amount(self, amount: float) -> "QueryBuilder":
-        """Filter by minimum amount."""
+        """Filter by minimum amount (ERC20, Native Token)."""
         return self._copy_with(min_amount=amount)
 
+    def max_amount(self, amount: float) -> "QueryBuilder":
+        """Filter by maximum amount (ERC20, Native Token)."""
+        return self._copy_with(max_amount=amount)
+
     # ERC20 specific
     def token(self, symbol: str) -> "QueryBuilder":
-        """Set token symbol (for ERC20)."""
+        """Set token symbol or address (ERC20)."""
         return self._copy_with(token=symbol)
 
-    def owner(self, address: str) -> "QueryBuilder":
-        """Filter by owner address (for approvals)."""
-        return self._copy_with(owner=address)
-
-    def spender(self, address: str) -> "QueryBuilder":
-        """Filter by spender address (for approvals)."""
-        return self._copy_with(spender=address)
+    def decimals(self, decimals: int) -> "QueryBuilder":
+        """Set token decimals when using custom address (ERC20). Default: 18."""
+        return self._copy_with(decimals=decimals)
 
     # AAVE specific
-    def user(self, address: str) -> "QueryBuilder":
-        """Filter by user address (for AAVE)."""
-        return self._copy_with(user=address)
-
-    def reserve(self, address: str) -> "QueryBuilder":
-        """Filter by reserve address (for AAVE)."""
-        return self._copy_with(reserve=address)
-
-    def liquidator(self, address: str) -> "QueryBuilder":
-        """Filter by liquidator address (for AAVE liquidations)."""
-        return self._copy_with(liquidator=address)
+    def eth_market_type(self, market_type: str) -> "QueryBuilder":
+        """Set AAVE market type for ETH network: 'Core', 'Prime', or 'EtherFi'. Default: 'Core'."""
+        return self._copy_with(eth_market_type=market_type)
 
     # Uniswap specific
     def symbol0(self, symbol: str) -> "QueryBuilder":
-        """Set first token symbol (for Uniswap)."""
+        """Set first token symbol (Uniswap)."""
         return self._copy_with(symbol0=symbol)
 
     def symbol1(self, symbol: str) -> "QueryBuilder":
-        """Set second token symbol (for Uniswap)."""
+        """Set second token symbol (Uniswap)."""
         return self._copy_with(symbol1=symbol)
 
     def fee(self, fee_tier: int) -> "QueryBuilder":
-        """Set fee tier (for Uniswap): 100, 500, 3000, 10000."""
+        """Set fee tier (Uniswap): 100, 500, 3000, 10000."""
         return self._copy_with(fee=fee_tier)
 
-    def pool(self, address: str) -> "QueryBuilder":
-        """Set pool address (for Uniswap)."""
-        return self._copy_with(pool=address)
-
     # Verbose mode
     def verbose(self, enabled: bool = True) -> "QueryBuilder":
         """Include all metadata fields (tx_hash, tx_id, log_index, network, name)."""
@@ -161,7 +147,7 @@ class QueryBuilder:
         """
         Execute query and return results as list of dictionaries.
 
-        Uses JSON format from API.
+        Uses JSON format from API. Limited to 10,000 blocks.
 
         Returns:
             List of event dictionaries
@@ -253,7 +239,7 @@ class AsyncQueryBuilder:
     - as_file() - saves to CSV, Parquet, or JSON file
 
     Example:
-        query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
+        query = client.erc20.transfers("USDT").network("ETH").block_range(21000000, 21010000)
         df = await query.as_df()  # pandas DataFrame
         df = await query.as_df("polars")  # polars DataFrame
         await query.as_file("transfers.csv")  # save to CSV
@@ -283,7 +269,7 @@ class AsyncQueryBuilder:
 
     # Network and block range
     def network(self, network: str) -> "AsyncQueryBuilder":
-        """Set the network (ETH, ARB, BASE, OP, etc.)."""
+        """Set the network (ETH, ARB, BASE, OP, POLYGON, etc.)."""
         return self._copy_with(network=network)
 
     def start_block(self, block: int) -> "AsyncQueryBuilder":
@@ -311,13 +297,13 @@ class AsyncQueryBuilder:
         """Set both start and end times."""
         return self._copy_with(since=start, until=end)
 
-    # Common filters
+    # ERC20 and Native Token filters
     def sender(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by sender address."""
+        """Filter by sender address (ERC20, Native Token)."""
         return self._copy_with(sender=address)
 
     def receiver(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address."""
+        """Filter by receiver address (ERC20, Native Token)."""
         return self._copy_with(receiver=address)
 
     def from_address(self, address: str) -> "AsyncQueryBuilder":
@@ -329,52 +315,40 @@ class AsyncQueryBuilder:
         return self.receiver(address)
 
     def min_amount(self, amount: float) -> "AsyncQueryBuilder":
-        """Filter by minimum amount."""
+        """Filter by minimum amount (ERC20, Native Token)."""
         return self._copy_with(min_amount=amount)
 
+    def max_amount(self, amount: float) -> "AsyncQueryBuilder":
+        """Filter by maximum amount (ERC20, Native Token)."""
+        return self._copy_with(max_amount=amount)
+
     # ERC20 specific
     def token(self, symbol: str) -> "AsyncQueryBuilder":
-        """Set token symbol (for ERC20)."""
+        """Set token symbol or address (ERC20)."""
         return self._copy_with(token=symbol)
 
-    def owner(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by owner address (for approvals)."""
-        return self._copy_with(owner=address)
-
-    def spender(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by spender address (for approvals)."""
-        return self._copy_with(spender=address)
+    def decimals(self, decimals: int) -> "AsyncQueryBuilder":
+        """Set token decimals when using custom address (ERC20). Default: 18."""
+        return self._copy_with(decimals=decimals)
 
     # AAVE specific
-    def user(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by user address (for AAVE)."""
-        return self._copy_with(user=address)
-
-    def reserve(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by reserve address (for AAVE)."""
-        return self._copy_with(reserve=address)
-
-    def liquidator(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by liquidator address (for AAVE liquidations)."""
-        return self._copy_with(liquidator=address)
+    def eth_market_type(self, market_type: str) -> "AsyncQueryBuilder":
+        """Set AAVE market type for ETH network: 'Core', 'Prime', or 'EtherFi'. Default: 'Core'."""
+        return self._copy_with(eth_market_type=market_type)
 
     # Uniswap specific
     def symbol0(self, symbol: str) -> "AsyncQueryBuilder":
-        """Set first token symbol (for Uniswap)."""
+        """Set first token symbol (Uniswap)."""
         return self._copy_with(symbol0=symbol)
 
     def symbol1(self, symbol: str) -> "AsyncQueryBuilder":
-        """Set second token symbol (for Uniswap)."""
+        """Set second token symbol (Uniswap)."""
         return self._copy_with(symbol1=symbol)
 
     def fee(self, fee_tier: int) -> "AsyncQueryBuilder":
-        """Set fee tier (for Uniswap): 100, 500, 3000, 10000."""
+        """Set fee tier (Uniswap): 100, 500, 3000, 10000."""
         return self._copy_with(fee=fee_tier)
 
-    def pool(self, address: str) -> "AsyncQueryBuilder":
-        """Set pool address (for Uniswap)."""
-        return self._copy_with(pool=address)
-
     # Verbose mode
     def verbose(self, enabled: bool = True) -> "AsyncQueryBuilder":
         """Include all metadata fields (tx_hash, tx_id, log_index, network, name)."""
@@ -393,7 +367,7 @@ class AsyncQueryBuilder:
         """
         Execute query and return results as list of dictionaries.
 
-        Uses JSON format from API.
+        Uses JSON format from API. Limited to 10,000 blocks.
 
         Returns:
             List of event dictionaries
@@ -405,8 +379,6 @@ class AsyncQueryBuilder:
         """
         Execute query and return results as DataFrame.
 
-        Uses Parquet format from API for efficiency, then converts to DataFrame.
-
         Args:
             library: DataFrame library to use - "pandas" (default) or "polars"
 

{defistream-1.0.0.dist-info → defistream-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.0.0
+Version: 1.0.2
 Summary: Python client for the DeFiStream API
 Project-URL: Homepage, https://defistream.dev
 Project-URL: Documentation, https://docs.defistream.dev
@@ -34,7 +34,11 @@ Description-Content-Type: text/markdown
 
 # DeFiStream Python Client
 
-Official Python client for the [DeFiStream API](https://defistream.dev) - access historical DeFi events from 45+ EVM networks.
+Official Python client for the [DeFiStream API](https://defistream.dev).
+
+## Getting an API Key
+
+To use the DeFiStream API, you need to sign up for an account at [defistream.dev](https://defistream.dev) to obtain your API key.
 
 ## Installation
 
@@ -61,44 +65,41 @@ client = DeFiStream()
 client = DeFiStream(api_key="dsk_your_api_key")
 
 # Query ERC20 transfers using builder pattern
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
-for transfer in transfers:
-    print(f"{transfer['sender']} -> {transfer['receiver']}: {transfer['amount']}")
+print(df.head())
 ```
 
 ## Features
 
 - **Builder pattern**: Fluent query API with chainable methods
 - **Type-safe**: Full type hints and Pydantic models
-- **Multiple formats**: JSON, CSV, Parquet, pandas DataFrame, polars DataFrame
+- **Multiple formats**: DataFrame (pandas/polars), CSV, Parquet, JSON
 - **Async support**: Native async/await with `AsyncDeFiStream`
-- **All protocols**: AAVE, Uniswap, Lido, ERC20, Native tokens, and more
-- **Verbose mode**: Include all metadata fields (tx_hash, tx_id, log_index, network, name)
+- **All protocols**: ERC20, AAVE, Uniswap, Lido, Stader, Threshold, Native tokens
 
 ## Supported Protocols
 
 | Protocol | Events |
 |----------|--------|
-| ERC20 | `transfers`, `approvals` |
+| ERC20 | `transfers` |
 | Native Token | `transfers` |
-| AAVE V3 | `deposits`, `withdrawals`, `borrows`, `repays`, `liquidations` |
-| Uniswap V3 | `swaps`, `mints`, `burns` |
-| Lido | `deposits`, `withdrawals` |
-| Stader | `deposits`, `withdrawals` |
-| Threshold | `mints`, `burns` |
+| AAVE V3 | `deposits`, `withdrawals`, `borrows`, `repays`, `flashloans`, `liquidations` |
+| Uniswap V3 | `swaps`, `deposits`, `withdrawals`, `collects` |
+| Lido | `deposits`, `withdrawal_requests`, `withdrawals_claimed`, `l2_deposits`, `l2_withdrawal_requests` |
+| Stader | `deposits`, `withdrawal_requests`, `withdrawals` |
+| Threshold | `deposit_requests`, `deposits`, `withdrawal_requests`, `withdrawals` |
 
 ## Usage Examples
 
 ### Builder Pattern
 
-The client uses a fluent builder pattern. The query is only executed when you call a terminal method like `as_dict()`, `as_df()`, or `as_file()`.
+The client uses a fluent builder pattern. The query is only executed when you call a terminal method like `as_df()`, `as_file()`, or `as_dict()`.
 
 ```python
 from defistream import DeFiStream
@@ -108,21 +109,19 @@ client = DeFiStream()
 # Build query step by step
 query = client.erc20.transfers("USDT")
 query = query.network("ETH")
-query = query.start_block(24000000)
-query = query.end_block(24100000)
+query = query.block_range(21000000, 21010000)
 query = query.min_amount(1000)
 
-# Execute and get results
-transfers = query.as_dict()
+# Execute and get DataFrame
+df = query.as_df()
 
 # Or chain everything
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .min_amount(1000)
-    .as_dict()
+    .as_df()
 )
 ```
 
@@ -130,35 +129,21 @@ transfers = (
 
 ```python
 # Get USDT transfers over 10,000 USDT
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .min_amount(10000)
-    .as_dict()
+    .as_df()
 )
 
 # Filter by sender
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .sender("0x28c6c06298d514db089934071355e5743bf21d60")
-    .as_dict()
-)
-
-# Or use aliases: from_address/to_address
-transfers = (
-    client.erc20.transfers()
-    .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .token("USDC")
-    .from_address("0x...")
-    .to_address("0x...")
-    .as_dict()
+    .as_df()
 )
 ```
 
@@ -166,22 +151,20 @@ transfers = (
 
 ```python
 # Get deposits
-deposits = (
+df = (
     client.aave.deposits()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
-# Get liquidations for a specific user
-liquidations = (
-    client.aave.liquidations()
+# Use a specific market type on ETH (Core, Prime, or EtherFi)
+df = (
+    client.aave.deposits()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .user("0x...")
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .eth_market_type("Prime")
+    .as_df()
 )
 ```
 
@@ -189,24 +172,22 @@ liquidations = (
 
 ```python
 # Get swaps for WETH/USDC pool with 0.05% fee tier
-swaps = (
+df = (
     client.uniswap.swaps("WETH", "USDC", 500)
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
 # Or build with chain methods
-swaps = (
+df = (
     client.uniswap.swaps()
     .symbol0("WETH")
     .symbol1("USDC")
     .fee(500)
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 ```
 
@@ -214,13 +195,12 @@ swaps = (
 
 ```python
 # Get ETH transfers >= 1 ETH
-transfers = (
+df = (
     client.native_token.transfers()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .min_amount(1.0)
-    .as_dict()
+    .as_df()
 )
 ```
 
@@ -230,25 +210,21 @@ By default, responses omit metadata fields to reduce payload size. Use `.verbose
 
 ```python
 # Default: compact response (no tx_hash, tx_id, log_index, network, name)
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
-# Returns: [{"block_number": 24000050, "sender": "0x...", "receiver": "0x...", "amount": 1000.0, ...}]
 
 # Verbose: includes all metadata fields
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .verbose()
-    .as_dict()
+    .as_df()
 )
-# Returns: [{"name": "TransferEvent", "network": "ETH", "tx_id": "0x...", "tx_hash": "0x...", "log_index": 5, "block_number": 24000050, ...}]
 ```
 
 ### Return as DataFrame
@@ -258,8 +234,7 @@ transfers = (
 df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .as_df()
 )
 
@@ -267,8 +242,7 @@ df = (
 df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .as_df("polars")
 )
 ```
@@ -278,43 +252,49 @@ df = (
 Format is automatically determined by file extension:
 
 ```python
-# Save as CSV
+# Save as Parquet (recommended for large datasets)
 (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_file("transfers.csv")
+    .block_range(21000000, 21100000)
+    .as_file("transfers.parquet")
 )
 
-# Save as Parquet
+# Save as CSV
 (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_file("transfers.parquet")
+    .block_range(21000000, 21100000)
+    .as_file("transfers.csv")
 )
 
 # Save as JSON
 (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .as_file("transfers.json")
 )
+```
 
-# Explicit format (when path has no extension)
-(
+### Return as Dictionary (JSON)
+
+For small queries, you can get results as a list of dictionaries:
+
+```python
+transfers = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_file("transfers", format="csv")
+    .block_range(21000000, 21010000)
+    .as_dict()
 )
+
+for transfer in transfers:
+    print(f"{transfer['sender']} -> {transfer['receiver']}: {transfer['amount']}")
 ```
 
+> **Note:** `as_dict()` and `as_file("*.json")` use JSON format which has a **10,000 block limit**. For larger block ranges, use `as_df()` or `as_file()` with `.parquet` or `.csv` extensions, which support up to 1,000,000 blocks.
+
 ### Async Usage
 
 ```python
@@ -323,41 +303,17 @@ from defistream import AsyncDeFiStream
 
 async def main():
     async with AsyncDeFiStream() as client:
-        transfers = await (
+        df = await (
             client.erc20.transfers("USDT")
             .network("ETH")
-            .start_block(24000000)
-            .end_block(24100000)
-            .as_dict()
+            .block_range(21000000, 21010000)
+            .as_df()
         )
-        print(f"Found {len(transfers)} transfers")
+        print(f"Found {len(df)} transfers")
 
 asyncio.run(main())
 ```
 
-### Multiple Networks in Parallel
-
-```python
-import asyncio
-from defistream import AsyncDeFiStream
-
-async def fetch_all_networks():
-    async with AsyncDeFiStream() as client:
-        networks = ["ETH", "ARB", "BASE", "OP"]
-        tasks = [
-            client.erc20.transfers("USDC")
-            .network(net)
-            .start_block(24000000)
-            .end_block(24100000)
-            .as_dict()
-            for net in networks
-        ]
-        results = await asyncio.gather(*tasks)
-        return dict(zip(networks, results))
-
-all_transfers = asyncio.run(fetch_all_networks())
-```
-
 ## Configuration
 
 ### Environment Variables
@@ -402,12 +358,11 @@ from defistream.exceptions import (
 client = DeFiStream()
 
 try:
-    transfers = (
+    df = (
         client.erc20.transfers("USDT")
         .network("ETH")
-        .start_block(24000000)
-        .end_block(24100000)
-        .as_dict()
+        .block_range(21000000, 21010000)
+        .as_df()
     )
 except AuthenticationError:
     print("Invalid API key")
@@ -426,12 +381,11 @@ except DeFiStreamError as e:
 Access rate limit and quota information:
 
 ```python
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
 # Access response metadata
@@ -446,7 +400,7 @@ print(f"Request cost: {client.last_response.request_cost}")
 
 | Method | Description |
 |--------|-------------|
-| `.network(net)` | Set network (ETH, ARB, BASE, OP, etc.) |
+| `.network(net)` | Set network (ETH, ARB, BASE, OP, POLYGON, etc.) |
 | `.start_block(n)` | Set starting block number |
 | `.end_block(n)` | Set ending block number |
 | `.block_range(start, end)` | Set both start and end blocks |
@@ -455,35 +409,30 @@ print(f"Request cost: {client.last_response.request_cost}")
 | `.time_range(start, end)` | Set both start and end times |
 | `.verbose()` | Include all metadata fields |
 
-### Filter Methods
+### Protocol-Specific Parameters
 
 | Method | Protocols | Description |
 |--------|-----------|-------------|
+| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC) or contract address |
+| `.decimals(n)` | ERC20 | Token decimals when using custom address (default: 18) |
 | `.sender(addr)` | ERC20, Native | Filter by sender address |
 | `.receiver(addr)` | ERC20, Native | Filter by receiver address |
-| `.from_address(addr)` | ERC20, Native | Alias for sender |
-| `.to_address(addr)` | ERC20, Native | Alias for receiver |
 | `.min_amount(amt)` | ERC20, Native | Minimum transfer amount |
-| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC, etc.) |
-| `.owner(addr)` | ERC20 Approvals, Lido | Filter by owner |
-| `.spender(addr)` | ERC20 Approvals | Filter by spender |
-| `.user(addr)` | AAVE | Filter by user |
-| `.reserve(addr)` | AAVE | Filter by reserve |
-| `.liquidator(addr)` | AAVE Liquidations | Filter by liquidator |
-| `.symbol0(sym)` | Uniswap | First token symbol |
-| `.symbol1(sym)` | Uniswap | Second token symbol |
-| `.fee(tier)` | Uniswap | Fee tier (100, 500, 3000, 10000) |
-| `.pool(addr)` | Uniswap | Pool address |
+| `.max_amount(amt)` | ERC20, Native | Maximum transfer amount |
+| `.eth_market_type(type)` | AAVE | Market type for ETH: 'Core', 'Prime', 'EtherFi' |
+| `.symbol0(sym)` | Uniswap | First token symbol (required) |
+| `.symbol1(sym)` | Uniswap | Second token symbol (required) |
+| `.fee(tier)` | Uniswap | Fee tier: 100, 500, 3000, 10000 (required) |
 
 ### Terminal Methods
 
 | Method | Description |
 |--------|-------------|
-| `.as_dict()` | Execute and return list of dicts (JSON) |
 | `.as_df()` | Execute and return pandas DataFrame |
 | `.as_df("polars")` | Execute and return polars DataFrame |
 | `.as_file(path)` | Execute and save to file (format from extension) |
 | `.as_file(path, format="csv")` | Execute and save with explicit format |
+| `.as_dict()` | Execute and return list of dicts (JSON, 10K block limit) |
 
 ## License
 

defistream-1.0.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+defistream/__init__.py,sha256=RUAlky12Gxi0hYBUeXJ32qkhku-BLs8cOqZCpC6nZE0,1680
+defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
+defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
+defistream/models.py,sha256=JiG4IUq19HIANz9MHQCkaE6onGNyNzXcbdJmosrHsw0,3812
+defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
+defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+defistream/query.py,sha256=cOGba8MQNFKXTs39csD81vrMW76c9O3-S40R0KAMyCA,17158
+defistream-1.0.2.dist-info/METADATA,sha256=MSChxyWWx6vCUALDfZFybRLcqJsKtyi56N4eY-i2vyE,10950
+defistream-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+defistream-1.0.2.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
+defistream-1.0.2.dist-info/RECORD,,

defistream-1.0.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-defistream/__init__.py,sha256=nXlmtbfyy4VrbZ8PRFzUW49R6DukTRZIxeeph_9k6UY,1827
-defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
-defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
-defistream/models.py,sha256=JiG4IUq19HIANz9MHQCkaE6onGNyNzXcbdJmosrHsw0,3812
-defistream/protocols.py,sha256=b9zX0RUaw9mwZA-rPCPfpRisN5X-mdwmXSoTPYS-ius,11811
-defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-defistream/query.py,sha256=73vu8uXBdiFqGKoU0nDHDQ8emLnt1HVJMmvrl--Hzmg,17791
-defistream-1.0.0.dist-info/METADATA,sha256=m6_u2yhrLNNHnm8HthaDx0pYpGtENY-CO7bz-qQeh94,12079
-defistream-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-defistream-1.0.0.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
-defistream-1.0.0.dist-info/RECORD,,